mirror of
https://gitee.com/mirrors_PX4/PX4-Autopilot.git
synced 2026-10-24 02:13:33 +08:00
Move PX4 Guide source into /docs (#24490)
* 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
co-authored by
Ramon Roche
Ramon Roche
parent
8e6d2ebe4a
commit
88d623bedb
@@ -0,0 +1,23 @@
|
||||
# Community Supported Developer Tools
|
||||
|
||||
This section contains information about _community-supported_ development setups, IDEs, simulators, and other tools.
|
||||
|
||||
:::warning
|
||||
These setups are not maintained, tested, or supported, by the core development team.
|
||||
They may or may not work with current versions of PX4.
|
||||
|
||||
See [Toolchain Installation](../dev_setup/dev_env.md) for information about the environments and tools supported by the core development team.
|
||||
:::
|
||||
|
||||
The tools have variable levels of support from their communities (some are well supported and others are not).
|
||||
Questions about these tools should be raised on the [discussion forums](../contribute/support.md#forums-and-chat)
|
||||
|
||||
- Development Platforms/Setups
|
||||
- [CentOS Linux](../dev_setup/dev_env_linux_centos.md)
|
||||
- [Arch Linux](../dev_setup/dev_env_linux_arch.md)
|
||||
- [Windows VM Toolchain](../dev_setup/dev_env_windows_vm.md) — Ubuntu setup running in VM on Windows.
|
||||
- [Windows Cygwin Toolchain](../dev_setup/dev_env_windows_cygwin.md) — Windows setup only works to PX4 v1.12
|
||||
- [Windows Cygwin Toolchain Maintenance](../dev_setup/dev_env_windows_cygwin_packager_setup.md)
|
||||
- IDEs
|
||||
- [Qt Creator IDE](../dev_setup/qtcreator.md)
|
||||
- [Simulators](../simulation/community_supported_simulators.md) — [Simulation-In-Hardware](../sim_sih/index.md), [FlightGear](../sim_flightgear/index.md), [JSBSim](../sim_jsbsim/index.md), [AirSim](../sim_airsim/index.md), [HITL](../simulation/hitl.md)
|
||||
@@ -0,0 +1,92 @@
|
||||
# Computer Vision (Optical Flow, MoCap, VIO, Avoidance)
|
||||
|
||||
[Computer vision](https://en.wikipedia.org/wiki/Computer_vision) techniques enable computers to use visual data to make sense of their environment.
|
||||
|
||||
PX4 uses computer vision systems (primarily running on [Companion Computers](../companion_computer/index.md)) in order to support the following features:
|
||||
|
||||
- [Optical Flow](#optical-flow) provides 2D velocity estimation (using a downward facing camera and a downward facing distance sensor).
|
||||
- [Motion Capture](#motion-capture) provides 3D pose estimation using a vision system that is _external_ to the vehicle.
|
||||
It is primarily used for indoor navigation.
|
||||
- [Visual Inertial Odometry](#visual-inertial-odometry-vio) provides 3D pose and velocity estimation using an onboard vision system and IMU.
|
||||
It is used for navigation when GNSS position information is absent or unreliable.
|
||||
- [Collision Prevention](../computer_vision/collision_prevention.md) is used to stop vehicles before they can crash into an obstacle (primarily when flying in manual modes).
|
||||
|
||||
:::tip
|
||||
The [PX4 Vision Autonomy Development Kit](../complete_vehicles_mc/px4_vision_kit.md) (Holybro) is a robust and inexpensive kit for developers working with computer vision on PX4.
|
||||
:::
|
||||
|
||||
## Motion Capture
|
||||
|
||||
Motion Capture (MoCap) is a technique for estimating the 3D _pose_ (position and orientation) of a vehicle using a positioning mechanism that is _external_ to the vehicle.
|
||||
MoCap systems most commonly detect motion using infrared cameras, but other types of cameras, Lidar, or Ultra Wideband (UWB) may also be used.
|
||||
|
||||
::: info
|
||||
MoCap is commonly used to navigate a vehicle in situations where GPS is absent (e.g. indoors), and provides position relative to a _local_ coordinate system.
|
||||
:::
|
||||
|
||||
For information about MoCap see:
|
||||
|
||||
- [External Position Estimation](../ros/external_position_estimation.md)
|
||||
- [Flying with Motion Capture (VICON, NOKOV, Optitrack)](../tutorials/motion-capture.md)
|
||||
- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
|
||||
|
||||
## Visual Inertial Odometry (VIO)
|
||||
|
||||
Visual Inertial Odometry (VIO) is used for estimating the 3D _pose_ (position and orientation) and _velocity_ of a moving vehicle relative to a _local_ starting position.
|
||||
It is commonly used to navigate a vehicle in situations where GPS is absent (e.g. indoors) or unreliable (e.g. when flying under a bridge).
|
||||
|
||||
VIO uses [Visual Odometry](https://en.wikipedia.org/wiki/Visual_odometry) to estimate vehicle _pose_ from visual information, combined with inertial measurements from an IMU (to correct for errors associated with rapid vehicle movement resulting in poor image capture).
|
||||
|
||||
::: info
|
||||
One difference between VIO and [MoCap](#motion-capture) is that VIO cameras/IMU are vehicle-based, and additionally provide velocity information.
|
||||
:::
|
||||
|
||||
For information about configuring VIO on PX4 see:
|
||||
|
||||
- [Using PX4's Navigation Filter (EKF2) > External Vision System](../advanced_config/tuning_the_ecl_ekf.md#external-vision-system)
|
||||
- [T265 Setup guide](../peripherals/camera_t265_vio.md)
|
||||
|
||||
## Optical Flow
|
||||
|
||||
[Optical Flow](../sensor/optical_flow.md) provides 2D velocity estimation (using a downward facing camera and a downward facing distance sensor).
|
||||
|
||||
For information about optical flow see:
|
||||
|
||||
- [Optical Flow](../sensor/optical_flow.md)
|
||||
- [Using PX4's Navigation Filter (EKF2) > Optical Flow](../advanced_config/tuning_the_ecl_ekf.md#optical-flow)
|
||||
|
||||
## Comparisons
|
||||
|
||||
### Optical Flow vs VIO for Local Position Estimation
|
||||
|
||||
Both these techniques use cameras and measure differences between frames.
|
||||
Optical flow uses a downward facing camera, while VIO uses a stereo camera or a 45 degree tracking camera.
|
||||
Assuming both are well calibrated, which is better for local position estimation?
|
||||
|
||||
The consensus [appears to be](https://discuss.px4.io/t/vio-vs-optical-flow/34680):
|
||||
|
||||
Optical flow:
|
||||
|
||||
- Downward facing optical flow gives you a planar velocity thats corrected for angular velocity with the gyro.
|
||||
- Requires an accurate distance to the ground and assumes a planar surface.
|
||||
Given those conditions it can be just as accurate/reliable as VIO (such as indoor flight)
|
||||
- Is more robust than VIO as it has fewer states.
|
||||
- Is significantly cheaper and easier to set up as it only requires a flow sensor, a rangefinder, and setting up a few parameters (which can be connected to the flight controller).
|
||||
|
||||
VIO:
|
||||
|
||||
- Is more expensive to purchase and harder to set up.
|
||||
It requires a separate companion computer, calibration, software, configuration and so on.
|
||||
- Will be less effective if there are no point features to track (in practice the real world generally has point features).
|
||||
- Is more flexible, allowing additional features such as obstacle avoidance and mapping.
|
||||
|
||||
A combination (fusing both) is probably the most reliable, though not necessary in most real-world scenarios.
|
||||
Normally you will select the system that suits your operating environment, required features, and cost constraints:
|
||||
|
||||
- Use VIO if you plan on flying outdoors without GPS (or outdoors and indoors), or if you need to support obstacle avoidance and other computer vision features.
|
||||
- Use Optical Flow if you plan on only flying indoors (without GPS) and cost is an important consideration.
|
||||
|
||||
## External Resources
|
||||
|
||||
- [XTDrone](https://github.com/robin-shaun/XTDrone/blob/master/README.en.md) - ROS + PX4 simulation environment for computer vision.
|
||||
The [XTDrone Manual](https://www.yuque.com/xtdrone/manual_en) has everything you need to get started!
|
||||
@@ -0,0 +1,185 @@
|
||||
# Gimbal Configuration
|
||||
|
||||
This page explains how to configure and control a gimbal that has an attached camera (or any other payload).
|
||||
|
||||
## Overview
|
||||
|
||||
PX4 contains a generic mount/gimbal control driver that supports different input and output methods:
|
||||
|
||||
- The input method defines the protocol used to command a gimbal mount that is managed by PX4.
|
||||
This might be an RC controller, a MAVLink command sent by a GCS, or both — automatically switching between them.
|
||||
- The output method defines how PX4 communicates with the connected gimbal.
|
||||
The recommended protocol is MAVLink v2, but you can also connect directly to a flight controller PWM output port.
|
||||
|
||||
PX4 takes the input signal and routes/translates it to be sent through to the output.
|
||||
Any input method can be selected to drive any output.
|
||||
|
||||
Both the input and output are configured using parameters.
|
||||
The input is set using the parameter [MNT_MODE_IN](../advanced_config/parameter_reference.md#MNT_MODE_IN).
|
||||
By default this is set to `Disabled (-1)` and the driver does not run.
|
||||
After selecting the input mode, reboot the vehicle to start the mount driver.
|
||||
|
||||
You should set `MNT_MODE_IN` to one of: `RC (1)`, `MAVlink gimbal protocol v2 (4)` or `Auto (0)` (the other options are deprecated).
|
||||
If you select `Auto (0)`, the gimbal will automatically select either RC or or MAVLink input based on the latest input.
|
||||
Note that the auto-switch from MAVLink to RC requires a large stick motion!
|
||||
|
||||
The output is set using the [MNT_MODE_OUT](../advanced_config/parameter_reference.md#MNT_MODE_OUT) parameter.
|
||||
By default the output is set to a PXM port (`AUX (0)`).
|
||||
If the [MAVLink Gimbal Protocol v2](https://mavlink.io/en/services/gimbal_v2.html) is supported by your gimbal, you should instead select `MAVLink gimbal protocol v2 (2)`.
|
||||
|
||||
The full list of parameters for setting up the mount driver can be found in [Parameter Reference > Mount](../advanced_config/parameter_reference.md#mount).
|
||||
The relevant settings for a number of common gimbal configurations are described below.
|
||||
|
||||
## MAVLink Gimbal (MNT_MODE_OUT=MAVLINK)
|
||||
|
||||
Each physical gimbal device on the system must have its own high level gimbal manager, which is discoverable by a ground station using the MAVLink gimbal protocol.
|
||||
The ground station sends high level [MAVLink Gimbal Manager](https://mavlink.io/en/services/gimbal_v2.html#gimbal-manager-messages) commands to the manager of the gimbal it wants to control, and the manager will in turn send appropriate lower level "gimbal device" commands to control the gimbal.
|
||||
|
||||
PX4 can be configured as the gimbal manager to control a single gimbal device (which can either be physically connected or be a MAVLink gimbal that implements the [gimbal device interface](https://mavlink.io/en/services/gimbal_v2.html#gimbal-device-messages)).
|
||||
|
||||
To enable a MAVLink gimbal, first set parameter [MNT_MODE_IN](../advanced_config/parameter_reference.md#MNT_MODE_IN) to `MAVlink gimbal protocol v2` and [MNT_MODE_OUT](../advanced_config/parameter_reference.md#MNT_MODE_OUT) to `MAVLink gimbal protocol v2`.
|
||||
|
||||
The gimbal can be connected to _any free serial port_ using the instructions in [MAVLink Peripherals (GCS/OSD/Companion)](../peripherals/mavlink_peripherals.md) (also see [Serial Port Configuration](../peripherals/serial_configuration.md#serial-port-configuration)).
|
||||
For example, if the `TELEM2` port on the flight controller is unused you can connect it to the gimbal and set the following PX4 parameters:
|
||||
|
||||
- [MAV_1_CONFIG](../advanced_config/parameter_reference.md#MAV_1_CONFIG) to **TELEM2** (if `MAV_1_CONFIG` is already used for a companion computer (say), use `MAV_2_CONFIG`).
|
||||
- [MAV_1_MODE](../advanced_config/parameter_reference.md#MAV_1_MODE) to **NORMAL**
|
||||
- [SER_TEL2_BAUD](../advanced_config/parameter_reference.md#SER_TEL2_BAUD) to manufacturer recommended baud rate.
|
||||
|
||||
### Multiple Gimbal Support
|
||||
|
||||
PX4 can automatically create a gimbal manager for a connected PWM gimbal or the first MAVLink gimbal device with the same system id it detects on any interface.
|
||||
It does not automatically create gimbal manager for any other MAVLink gimbal devices that it detects.
|
||||
|
||||
You can support additional MAVLink gimbals provided that they:
|
||||
|
||||
- Implement the gimbal _manager_ protocol.
|
||||
- Are visible to the ground station and PX4 on the MAVLink network.
|
||||
This may require that traffic forwarding be configured between PX4, the GCS, and the gimbal.
|
||||
- Have a unique component id, and this component id must be in the range 7 - 255.
|
||||
|
||||
## Gimbal on FC PWM Output (MNT_MODE_OUT=AUX)
|
||||
|
||||
The gimbal can also be controlled by connecting it to up to three flight controller PWM ports and setting the output mode to `MNT_MODE_OUT=AUX`.
|
||||
|
||||
The output pins that are used to control the gimbal are set in the [Acuator Configuration > Outputs](../config/actuators.md#actuator-outputs) by selecting any three unused Actuator Outputs and assigning them the following output functions:
|
||||
|
||||
- `Gimbal Roll`: Output controls gimbal roll.
|
||||
- `Gimbal Pitch`: Output controls Gimbal pitch.
|
||||
- `Gimbal Yaw`: Output controls Gimbal yaw.
|
||||
|
||||
For example, you might have the following settings to assign the gimbal roll, pitch and yaw to AUX1-3 outputs.
|
||||
|
||||
|
||||
|
||||
The PWM values to use for the disarmed, maximum and minimum values can be determined in the same way as other servo, using the [Actuator Test sliders](../config/actuators.md#actuator-testing) to confirm that each slider moves the appropriate axis, and changing the values so that the gimbal is in the appropriate position at the disarmed, low and high position in the slider.
|
||||
The values may also be provided in gimbal documentation.
|
||||
|
||||
## Gimbal Control in Missions
|
||||
|
||||
[Gimbal Manager commands](https://mavlink.io/en/services/gimbal_v2.html#gimbal-manager-messages) may be used in missions if supported by the vehicle type.
|
||||
For example [MAV_CMD_DO_GIMBAL_MANAGER_PITCHYAW](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_GIMBAL_MANAGER_PITCHYAW) is supported in [multicopter mission mode](../flight_modes_mc/mission.md).
|
||||
|
||||
In theory you can address commands to a particular gimbal, specifying its component id using the "Gimbal device id" parameter.
|
||||
However at time of writing (December 2024) this is [not supported](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/gimbal/input_mavlink.cpp#L889): all mission commands are sent to the (only) gimbal managed by the PX4 gimbal manager (if this is a MAVLink gimbal, it will be the gimbal with component id defined in the parameter [MNT_MAV_COMPID](../advanced_config/parameter_reference.md#MNT_MAV_COMPID), which is set by default to [MAV_COMP_ID_GIMBAL (154)](https://mavlink.io/en/messages/common.html#MAV_COMP_ID_GIMBAL)).
|
||||
|
||||
Gimbal movement is not immediate.
|
||||
To ensure that the gimbal has time to move into position before the mission progresses to the next item (if gimbal feedback is not provided or lost), you should set [MIS_COMMAND_TOUT](../advanced_config/parameter_reference.md#MIS_COMMAND_TOUT) to be greater than the time taken for the gimbal to traverse its full range.
|
||||
After this timeout the mission will proceed to the next item.
|
||||
|
||||
## Simulation / SITL
|
||||
|
||||
The following simulation environments come with a preconfigured simulated gimbal.
|
||||
You can test the gimbal using the [QGroundControl UI](#qgc-testing) or by sending [driver commands](#driver-testing)
|
||||
|
||||
::: tip
|
||||
If you only need to test the [gimbal driver](../modules/modules_driver.md#gimbal), then you can do this on any model or simulators.
|
||||
Just make sure that the driver runs, using `gimbal start` in the MAVLink console, then configure the driver parameters.
|
||||
:::
|
||||
|
||||
### Gazebo
|
||||
|
||||
To run the [Gazebo](../sim_gazebo_gz/index.md) simulation [Quadrotor(x500) with gimbal (Front-facing) in Gazebo](../sim_gazebo_gz/vehicles.md#x500-quadrotor-with-gimbal-front-facing), use:
|
||||
|
||||
```sh
|
||||
make px4_sitl gz_x500_gimbal
|
||||
```
|
||||
|
||||
|
||||
|
||||
### Gazebo Classic
|
||||
|
||||
To run the [Gazebo Classic](../sim_gazebo_classic/index.md) simulation [Typhoon H480 model](../sim_gazebo_classic/vehicles.md#typhoon-h480-hexrotor), use:
|
||||
|
||||
```sh
|
||||
make px4_sitl gazebo-classic_typhoon_h480
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Testing
|
||||
|
||||
### QGC Testing
|
||||
|
||||
The on-screen gimbal control can be used to move/test a connected MAVLink camera:
|
||||
|
||||
1. Start your preferred [simulator](#simulation-sitl) or connect to a real device.
|
||||
2. Open QGroundControl and enable the on-screen camera control (Application settings).
|
||||
|
||||
|
||||
|
||||
3. Make sure the vehicle is armed and flying, e.g. by entering with `commander takeoff`.
|
||||
4. To change gimbal target position, click in the QGC GUI up, down, left, right, or use the buttons on the gimbal control (**Center**, **Tilt 90**, **Yaw lock**).
|
||||
|
||||
### Driver Testing
|
||||
|
||||
You can test a gimbal by sending `gimbal` driver commands in the [QGroundControl MAVLink Console](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/analyze_view/mavlink_console.html):
|
||||
|
||||
1. Start your preferred [simulator](#simulation-sitl) or connect to a real device.
|
||||
2. Open QGroundControl and connect to your vehicle.
|
||||
3. Open the MAVLink Console using the menu: **Analyze > Mavlink Console**.
|
||||
4. Make sure the vehicle is armed and flying, e.g. by entering the command: `commander takeoff`.
|
||||
|
||||
To check gimbal status enter:
|
||||
|
||||
```sh
|
||||
gimbal status
|
||||
```
|
||||
|
||||
To set the gimbal yaw to 30 degrees, use the command:
|
||||
|
||||
```sh
|
||||
gimbal test yaw 30
|
||||
```
|
||||
|
||||
More generally, you can set the angle or angular rate command using a command with this format:
|
||||
|
||||
```sh
|
||||
gimbal test <axis> <value>
|
||||
```
|
||||
|
||||
- `axis`:
|
||||
- `<roll|pitch|yaw>` for angles
|
||||
- `<rollrate|pitchrate|yawrate>` for angular rates
|
||||
- `value`:
|
||||
- `<degrees>` for angles
|
||||
- `<degrees / second>` for angular rates
|
||||
|
||||
To set the MAVLink component that is in primary control of the gimbal:
|
||||
|
||||
```sh
|
||||
gimbal primary-control <sys_id> <comp_id>
|
||||
```
|
||||
|
||||
- `sys_id`: MAVLink system ID
|
||||
- `comp_id`: MAVLink component ID
|
||||
|
||||
For other commands, see the [`gimbal`](../modules/modules_driver.md#gimbal) driver module document.
|
||||
|
||||
### MAVLink Testing
|
||||
|
||||
The gimbal can be tested by sending MAVLink gimbal manager commands using [MAVSDK](../robotics/mavsdk.md) or some other MAVLink library.
|
||||
|
||||
Note that the simulated gimbal stabilizes itself, so if you send MAVLink commands, set the `stabilize` flags to `false`.
|
||||
@@ -0,0 +1 @@
|
||||
# Advanced Topics
|
||||
@@ -0,0 +1,84 @@
|
||||
# External Modules (Out-of-Tree)
|
||||
|
||||
External modules provide a convenient mechanism for developers to manage/group proprietary modules that they want add to (or update in) PX4 firmware.
|
||||
External modules can use the same includes as internal modules and can interact with internal modules via uORB.
|
||||
|
||||
This topic explains how to add an external ("out of tree") module to the PX4 build.
|
||||
|
||||
:::tip
|
||||
We encourage you to contribute your changes into PX4, where possible!
|
||||
:::
|
||||
|
||||
## Usage
|
||||
|
||||
To create an external module:
|
||||
|
||||
- Create an _external directory_ folder for grouping the external modules:
|
||||
- This can be located anywhere outside of the **PX4-Autopilot** tree.
|
||||
- It must have the same structure as **PX4-Autopilot** (i.e. it must contain a directory called **src**).
|
||||
- Later we refer to this directory using `EXTERNAL_MODULES_LOCATION`.
|
||||
- Copy an existing module (e.g. **examples/px4_simple_app**) to the external directory, or directly create a new module.
|
||||
- Rename the module (including `MODULE` in **CMakeLists.txt**) or remove it from the existing PX4-Autopilot _cmake_ build config.
|
||||
This is to avoid conflicts with internal modules.
|
||||
- Add a file **CMakeLists.txt** in the external directory with content:
|
||||
|
||||
```cmake
|
||||
set(config_module_list_external
|
||||
modules/<new_module>
|
||||
PARENT_SCOPE
|
||||
)
|
||||
```
|
||||
|
||||
- Add a line `EXTERNAL` to the `modules/<new_module>/CMakeLists.txt` within
|
||||
`px4_add_module()`, for example like this:
|
||||
|
||||
```cmake
|
||||
px4_add_module(
|
||||
MODULE modules__test_app
|
||||
MAIN test_app
|
||||
STACK_MAIN 2000
|
||||
SRCS
|
||||
px4_simple_app.c
|
||||
DEPENDS
|
||||
platforms__common
|
||||
EXTERNAL
|
||||
)
|
||||
```
|
||||
|
||||
## Out-of-Tree uORB Message Definitions
|
||||
|
||||
uORB messages can also be defined out-of-tree. For this, the `$EXTERNAL_MODULES_LOCATION/msg` folder must exist.
|
||||
|
||||
- Place all new message definitions within the `$EXTERNAL_MODULES_LOCATION/msg` directory.
|
||||
The format of these new out-of-tree message definitions are the same as for any other [uORB message definition](../middleware/uorb.md#adding-a-new-topic).
|
||||
- Add a file `$EXTERNAL_MODULES_LOCATION/msg/CMakeLists.txt` with content:
|
||||
|
||||
```cmake
|
||||
set(config_msg_list_external
|
||||
<message1>.msg
|
||||
<message2>.msg
|
||||
<message3>.msg
|
||||
PARENT_SCOPE
|
||||
)
|
||||
```
|
||||
|
||||
where `<message#>.msg` is the name of the uORB message definition file to be processed and used for uORB message generation.
|
||||
|
||||
The out-of-tree uORB messages will be generated in the same locations as the normal uORB messages.
|
||||
The uORB topic headers are generated in `<build_dir>/uORB/topics/`, and the message source files are
|
||||
generated in `<build_dir>/msg/topics_sources/`.
|
||||
|
||||
The new uORB messages can be used like any other uORB message as described [here](../middleware/uorb.md#adding-a-new-topic).
|
||||
|
||||
:::warning
|
||||
The out-of-tree uORB message definitions cannot have the same name as any of the normal uORB messages.
|
||||
:::
|
||||
|
||||
## Building External Modules and uORB Messages
|
||||
|
||||
Execute `make px4_sitl EXTERNAL_MODULES_LOCATION=<path>`.
|
||||
|
||||
Any other build target can be used, but the build directory must not yet exist.
|
||||
If it already exists, you can also just set the _cmake_ variable in the build folder.
|
||||
|
||||
For subsequent incremental builds `EXTERNAL_MODULES_LOCATION` does not need to be specified.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Package Delivery in Missions
|
||||
|
||||
<Badge type="tip" text="PX4 v1.14" />
|
||||
|
||||
A package delivery mission is an extension of a waypoint mission, where a user can plan delivering a package as a waypoint.
|
||||
|
||||
This topic explains the architecture for the package delivery feature.
|
||||
It is intended for developers working on extending the architecture, for example to support new payload delivery mechanisms.
|
||||
|
||||
::: info
|
||||
Currently only [Grippers](../peripherals/gripper.md) can be used for package delivery.
|
||||
Winches are not yet supported.
|
||||
:::
|
||||
|
||||
::: info
|
||||
The detailed documentation on how to setup a package delivery mission plan can be found [here](../flying/package_delivery_mission.md).
|
||||
Setup for the `payload_deliverer` module is covered in the documentation for the delivery mechanism, such as [Gripper](../peripherals/gripper.md#px4-configuration).
|
||||
:::
|
||||
|
||||
## Package Delivery Architecture Diagram
|
||||
|
||||
|
||||
|
||||
Package Delivery feature is centered around the [VehicleCommand](../msg_docs/VehicleCommand.md) & [VehicleCommandAck](../msg_docs/VehicleCommandAck.md) messages.
|
||||
|
||||
The central idea lies in having an entity that handles the `DO_GRIPPER` or `DO_WINCH` vehicle command, executes it and sends back an acknowledgement when the successful delivery is confirmed.
|
||||
|
||||
Because PX4 automatically broadcasts the `VehicleCommand` uORB message to a UART port configured to communicate in MAVLink as a [`COMMAND_LONG`](https://mavlink.io/en/messages/common.html#COMMAND_LONG) message, an external payload can receive the command and execute it.
|
||||
|
||||
Likewise, since PX4 automatically translates the [`COMMAND_ACK`](https://mavlink.io/en/messages/common.html#COMMAND_ACK) message coming in from an external source through a UART port configured for MAVLink into a `vehicle_command_ack` uORB message, an external payload's acknowledgement for a successful package deployment can be received by PX4's `navigator` module.
|
||||
|
||||
Below, each entity involved in the package delivery architecture is explained.
|
||||
|
||||
## Navigator
|
||||
|
||||
Navigator handles the reception of the vehicle command ACK (described below).
|
||||
Upon reception of a successful deployment ack message, it sets the flag in Mission block level to signal that the payload deployment has been successful.
|
||||
|
||||
This allows the mission to proceed to a next item (e.g. Waypoint) safely, as we are sure with the acknowledgement that the deployment has been successful.
|
||||
|
||||
## Vehicle Command ACK
|
||||
|
||||
We are waiting for the ACK coming from either internally (via `payload_deliverer` module), or externally (external entity sending the MAVLink message `COMMAND_ACK`) to determine if the package delivery action has been successful (either `DO_GRIPPER` or `DO_WINCH`).
|
||||
|
||||
## Mission
|
||||
|
||||
The Gripper / Winch command is placed as a `Mission Item`.
|
||||
This is possible since all the Mission item has the `MAV_CMD` to execute (e.g. Land, Takeoff, Waypoint, etc) which can get set to either `DO_GRIPPER` or `DO_WINCH`.
|
||||
|
||||
In the Mission logic (green box above) if either Gripper/Winch mission item is reached, it implements brake_for_hold functionality (which sets the `valid` flag of the next mission item waypoint to `false`) for rotary wings (e.g. Multicopter) so that the vehicle would hold it's position while the deployment is getting executed.
|
||||
|
||||
For fixed-wing and other vehicles, no special braking condition is considered.
|
||||
So if you have a loiter mission item for a fixed-wing, it will execute the delivery whilst doing the loiter, and won’t come to a stop (as it’s impossible)
|
||||
|
||||
## Mission Block
|
||||
|
||||
`MissionBlock` is the parent class of `Mission` that handles the part "Is Mission completed?".
|
||||
|
||||
This all performed in the `is_mission_item_reached_or_completed` function, to handle the time delay / mission item advancement.
|
||||
|
||||
Also it implements the actual issue_command function, which will issue a vehicle command corresponding to the mission item's `MAV_CMD`, which will then be received by an external payload or the `payload_deliverer` module internally.
|
||||
|
||||
## Payload Deliverer
|
||||
|
||||
This is a dedicated module that handles gripper / winch support, which is used for the standard [package delivery mission plan](../flying/package_delivery_mission.md).
|
||||
|
||||
Setup for the `payload_deliverer` module is covered within setting up an actual package release mechanism setup documentation like [Gripper](../peripherals/gripper.md#px4-configuration).
|
||||
@@ -0,0 +1,365 @@
|
||||
# Parameters & Configurations
|
||||
|
||||
PX4 uses the _param subsystem_ (a flat table of `float` and `int32_t` values) and text files (for startup scripts) to store its configuration.
|
||||
|
||||
This section discusses the _param_ subsystem in detail.
|
||||
It covers how to list, save and load parameters, and how to define them and make them available to ground stations.
|
||||
|
||||
:::tip
|
||||
[System startup](../concept/system_startup.md) and the way that [frame configuration](../dev_airframes/adding_a_new_frame.md) startup scripts work are detailed on other pages.
|
||||
:::
|
||||
|
||||
## Command Line Usage
|
||||
|
||||
The PX4 [system console](../debug/system_console.md) offers the [param](../modules/modules_command.md#param) tool, which can be used to set parameters, read their value, save them, and export and restore to/from files.
|
||||
|
||||
### Getting and Setting Parameters
|
||||
|
||||
The `param show` command lists all system parameters:
|
||||
|
||||
```sh
|
||||
param show
|
||||
```
|
||||
|
||||
To be more selective, a partial parameter name with wildcard "\*" can be used:
|
||||
|
||||
```sh
|
||||
nsh> param show RC_MAP_A*
|
||||
Symbols: x = used, + = saved, * = unsaved
|
||||
x RC_MAP_AUX1 [359,498] : 0
|
||||
x RC_MAP_AUX2 [360,499] : 0
|
||||
x RC_MAP_AUX3 [361,500] : 0
|
||||
x RC_MAP_ACRO_SW [375,514] : 0
|
||||
|
||||
723 parameters total, 532 used.
|
||||
```
|
||||
|
||||
You can use the `-c` flag to show all parameters that have changed (from their defaults):
|
||||
|
||||
```sh
|
||||
param show -c
|
||||
```
|
||||
|
||||
You can use `param show-for-airframe` to show all parameters that have changed from their defaults for just the current airframe's definition file (and defaults it imports).
|
||||
|
||||
### Exporting and Loading Parameters
|
||||
|
||||
You can save any parameters that have been _changed_ (that are different from airframe defaults).
|
||||
|
||||
The standard `param save` command will store the parameters in the current default file:
|
||||
|
||||
```sh
|
||||
param save
|
||||
```
|
||||
|
||||
If provided with an argument, it will store the parameters instead to this new location:
|
||||
|
||||
```sh
|
||||
param save /fs/microsd/vtol_param_backup
|
||||
```
|
||||
|
||||
There are two different commands to _load_ parameters:
|
||||
|
||||
- `param load` first does a full reset of all parameters to their defaults, and then overwrites parameter values with any values stored in the file.
|
||||
- `param import` just overwrites parameter values with the values from the file and then saves the result (i.e. effectively calls `param save`).
|
||||
|
||||
The `load` effectively resets the parameters to the state when the parameters were saved (we say "effectively" because any parameters saved in the file will be updated, but other parameters may have different firmware-defined default values than when the parameters file was created).
|
||||
|
||||
By contrast, `import` merges the parameters in the file with the current state of the vehicle.
|
||||
This can be used, for example, to just import a parameter file containing calibration data, without overwriting the rest of the system configuration.
|
||||
|
||||
Examples for both cases are shown below:
|
||||
|
||||
```sh
|
||||
# Reset the parameters to when file was saved
|
||||
param load /fs/microsd/vtol_param_backup
|
||||
# Optionally save params (not done automatically with load)
|
||||
param save
|
||||
```
|
||||
|
||||
```sh
|
||||
# Merge the saved parameters with current parameters
|
||||
param import /fs/microsd/vtol_param_backup
|
||||
```
|
||||
|
||||
## Creating/Defining Parameters
|
||||
|
||||
Parameters definitions have two parts:
|
||||
|
||||
- [Parameter metadata](#parameter-metadata) specifies the default value for each parameter in firmware along with other metadata for presentation (and editing) of parameters in ground control stations and documentation.
|
||||
- [C/C++ Code](#c-c-api) that provides access to get and/or subscribe to parameter values from within PX4 modules and drivers.
|
||||
|
||||
Several approaches are described below for writing both the metadata and code.
|
||||
Where possible code should use newer [YAML metadata](#yaml-metadata) and [C++ API](#c-api) over the older C parameter/code definitions, as these are more flexible and robust.
|
||||
|
||||
Parameter metadata is [compiled into the firmware](#publishing-parameter-metadata-to-a-gcs),
|
||||
and made available to ground stations via the [MAVLink Component Information service](https://mavlink.io/en/services/component_information.html).
|
||||
|
||||
### Parameter Names
|
||||
|
||||
Parameter names must be no more than 16 ASCII characters.
|
||||
|
||||
By convention, every parameter in a group should share the same (meaningful) string prefix followed by an underscore, and `MC_` and `FW_` are used for parameters related specifically to Multicopter or Fixed-wing systems.
|
||||
This convention is not enforced.
|
||||
|
||||
The name must match in both code and [parameter metadata](#parameter-metadata) to correctly associate the parameter with its metadata (including default value in Firmware).
|
||||
|
||||
### C / C++ API
|
||||
|
||||
There are separate C and C++ APIs that can be used to access parameter values from within PX4 modules and drivers.
|
||||
|
||||
One important difference between the APIs is that the C++ version has a more efficient standardized mechanism to synchronize with changes to parameter values (i.e. from a GCS).
|
||||
|
||||
Synchronization is important because a parameter can be changed to another value at any time.
|
||||
Your code should _always_ use the current value from the parameter store.
|
||||
If getting the latest version is not possible, then a reboot will be required after the parameter is changed (set this requirement using the `@reboot_required` metadata).
|
||||
|
||||
In addition, the C++ version has also better type-safety and less overhead in terms of RAM.
|
||||
The drawback is that the parameter name must be known at compile-time, while the C API can take a dynamically created name as a string.
|
||||
|
||||
#### C++ API
|
||||
|
||||
The C++ API provides macros to declare parameters as _class attributes_.
|
||||
You add some "boilerplate" code to regularly listen for changes in the [uORB Topic](../middleware/uorb.md) associated with _any_ parameter update.
|
||||
Framework code then (invisibly) handles tracking uORB messages that affect your parameter attributes and keeping them in sync.
|
||||
In the rest of the code you can just use the defined parameter attributes and they will always be up to date!
|
||||
|
||||
First include the required needed headers in the class header for your module or driver:
|
||||
|
||||
- **px4_platform_common/module_params.h** to get the `DEFINE_PARAMETERS` macro:
|
||||
|
||||
```cpp
|
||||
#include <px4_platform_common/module_params.h>
|
||||
```
|
||||
|
||||
- **parameter_update.h** to access the uORB `parameter_update` message:
|
||||
|
||||
```cpp
|
||||
#include <uORB/topics/parameter_update.h>
|
||||
```
|
||||
|
||||
- **Subscription.hpp** for the uORB C++ subscription API:
|
||||
|
||||
```cpp
|
||||
#include <uORB/Subscription.hpp>
|
||||
```
|
||||
|
||||
Derive your class from `ModuleParams`, and use `DEFINE_PARAMETERS` to specify a list of parameters and their associated parameter attributes.
|
||||
The names of the parameters must be the same as their parameter metadata definitions.
|
||||
|
||||
```cpp
|
||||
class MyModule : ..., public ModuleParams
|
||||
{
|
||||
public:
|
||||
...
|
||||
|
||||
private:
|
||||
|
||||
/**
|
||||
* Check for parameter changes and update them if needed.
|
||||
*/
|
||||
void parameters_update();
|
||||
|
||||
DEFINE_PARAMETERS(
|
||||
(ParamInt<px4::params::SYS_AUTOSTART>) _sys_autostart, /**< example parameter */
|
||||
(ParamFloat<px4::params::ATT_BIAS_MAX>) _att_bias_max /**< another parameter */
|
||||
)
|
||||
|
||||
// Subscriptions
|
||||
uORB::SubscriptionInterval _parameter_update_sub{ORB_ID(parameter_update), 1_s};
|
||||
|
||||
};
|
||||
```
|
||||
|
||||
Update the cpp file with boilerplate to check for the uORB message related to parameter updates.
|
||||
|
||||
Call `parameters_update();` periodically in code to check if there has been an update:
|
||||
|
||||
```cpp
|
||||
void Module::parameters_update()
|
||||
{
|
||||
if (_parameter_update_sub.updated()) {
|
||||
parameter_update_s param_update;
|
||||
_parameter_update_sub.copy(¶m_update);
|
||||
|
||||
// If any parameter updated, call updateParams() to check if
|
||||
// this class attributes need updating (and do so).
|
||||
updateParams();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In the above method:
|
||||
|
||||
- `_parameter_update_sub.updated()` tells us if there is _any_ update to the `param_update` uORB message (but not what parameter is affected).
|
||||
- If there has been "some" parameter updated, we copy the update into a `parameter_update_s` (`param_update`), to clear the pending update.
|
||||
- Then we call `ModuleParams::updateParams()`.
|
||||
This "under the hood" updates all parameter attributes listed in our `DEFINE_PARAMETERS` list.
|
||||
|
||||
The parameter attributes (`_sys_autostart` and `_att_bias_max` in this case) can then be used to represent the parameters, and will be updated whenever the parameter value changes.
|
||||
|
||||
:::tip
|
||||
The [Application/Module Template](../modules/module_template.md) uses the new-style C++ API but does not include [parameter metadata](#parameter-metadata).
|
||||
:::
|
||||
|
||||
#### C API
|
||||
|
||||
The C API can be used within both modules and drivers.
|
||||
|
||||
First include the parameter API:
|
||||
|
||||
```C
|
||||
#include <parameters/param.h>
|
||||
```
|
||||
|
||||
Then retrieve the parameter and assign it to a variable (here `my_param`), as shown below for `PARAM_NAME`.
|
||||
The variable `my_param` can then be used in your module code.
|
||||
|
||||
```C
|
||||
int32_t my_param = 0;
|
||||
param_get(param_find("PARAM_NAME"), &my_param);
|
||||
```
|
||||
|
||||
::: info
|
||||
If `PARAM_NAME` was declared in parameter metadata then its default value will be set, and the above call to find the parameter should always succeed.
|
||||
:::
|
||||
|
||||
`param_find()` is an "expensive" operation, which returns a handle that can be used by `param_get()`.
|
||||
If you're going to read the parameter multiple times, you may cache the handle and use it in `param_get()` when needed
|
||||
|
||||
```cpp
|
||||
# Get the handle to the parameter
|
||||
param_t my_param_handle = PARAM_INVALID;
|
||||
my_param_handle = param_find("PARAM_NAME");
|
||||
|
||||
# Query the value of the parameter when needed
|
||||
int32_t my_param = 0;
|
||||
param_get(my_param_handle, &my_param);
|
||||
```
|
||||
|
||||
### Parameter Metadata
|
||||
|
||||
PX4 uses an extensive parameter metadata system to drive the user-facing presentation of parameters, and to set the default value for each parameter in firmware.
|
||||
|
||||
:::tip
|
||||
Correct metadata is critical for good user experience in a ground station.
|
||||
:::
|
||||
|
||||
Parameter metadata can be stored anywhere in the source tree as either **.c** or **.yaml** parameter definitions (the YAML definition is newer, and more flexible).
|
||||
Typically it is stored alongside its associated module.
|
||||
|
||||
The build system extracts the metadata (using `make parameters_metadata`) to build the [parameter reference](../advanced_config/parameter_reference.md) and the parameter information [used by ground stations](#publishing-parameter-metadata-to-a-gcs).
|
||||
|
||||
:::warning
|
||||
After adding a _new_ parameter file you should call `make clean` before building to generate the new parameters (parameter files are added as part of the _cmake_ configure step, which happens for clean builds and if a cmake file is modified).
|
||||
:::
|
||||
|
||||
#### YAML Metadata
|
||||
|
||||
::: info
|
||||
At time of writing YAML parameter definitions cannot be used in _libraries_.
|
||||
:::
|
||||
|
||||
YAML meta data is intended as a full replacement for the **.c** definitions.
|
||||
It supports all the same metadata, along with new features like multi-instance definitions.
|
||||
|
||||
- The YAML parameter metadata schema is here: [validation/module_schema.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/validation/module_schema.yaml).
|
||||
- An example of YAML definitions being used can be found in the MAVLink parameter definitions: [/src/modules/mavlink/module.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/module.yaml).
|
||||
- A YAML file is registered in the cmake build system by adding
|
||||
|
||||
```cmake
|
||||
MODULE_CONFIG
|
||||
module.yaml
|
||||
```
|
||||
|
||||
to the `px4_add_module` section of the `CMakeLists.txt` file of that module.
|
||||
|
||||
#### Multi-Instance (Templated) YAML Meta Data
|
||||
|
||||
Templated parameter definitions are supported in [YAML parameter definitions](https://github.com/PX4/PX4-Autopilot/blob/main/validation/module_schema.yaml) (templated parameter code is not supported).
|
||||
|
||||
The YAML allows you to define instance numbers in parameter names, descriptions, etc. using `${i}`.
|
||||
For example, below will generate MY_PARAM_1_RATE, MY_PARAM_2_RATE etc.
|
||||
|
||||
```yaml
|
||||
MY_PARAM_${i}_RATE:
|
||||
description:
|
||||
short: Maximum rate for instance ${i}
|
||||
```
|
||||
|
||||
The following YAML definitions provide the start and end indexes.
|
||||
|
||||
- `num_instances` (default 1): Number of instances to generate (>=1)
|
||||
- `instance_start` (default 0): First instance number. If 0, `${i}` expands to [0, N-1]`.
|
||||
|
||||
For a full example see the MAVLink parameter definitions: [/src/modules/mavlink/module.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/mavlink/module.yaml)
|
||||
|
||||
#### c Parameter Metadata
|
||||
|
||||
The legacy approach for defining parameter metadata is in a file with extension **.c** (at time of writing this is the approach most commonly used in the source tree).
|
||||
|
||||
Parameter metadata sections look like the following examples:
|
||||
|
||||
```cpp
|
||||
/**
|
||||
* Pitch P gain
|
||||
*
|
||||
* Pitch proportional gain, i.e. desired angular speed in rad/s for error 1 rad.
|
||||
*
|
||||
* @unit 1/s
|
||||
* @min 0.0
|
||||
* @max 10
|
||||
* @decimal 2
|
||||
* @increment 0.0005
|
||||
* @reboot_required true
|
||||
* @group Multicopter Attitude Control
|
||||
*/
|
||||
PARAM_DEFINE_FLOAT(MC_PITCH_P, 6.5f);
|
||||
```
|
||||
|
||||
```cpp
|
||||
/**
|
||||
* Acceleration compensation based on GPS
|
||||
* velocity.
|
||||
*
|
||||
* @group Attitude Q estimator
|
||||
* @boolean
|
||||
*/
|
||||
PARAM_DEFINE_INT32(ATT_ACC_COMP, 1);
|
||||
```
|
||||
|
||||
The `PARAM_DEFINE_*` macro at the end specifies the type of parameter (`PARAM_DEFINE_FLOAT` or `PARAM_DEFINE_INT32`), the name of the parameter (which must match the name used in code), and the default value in firmware.
|
||||
|
||||
The lines in the comment block are all optional, and are primarily used to control display and editing options within a ground station.
|
||||
The purpose of each line is given below (for more detail see [module_schema.yaml](https://github.com/PX4/PX4-Autopilot/blob/main/validation/module_schema.yaml)).
|
||||
|
||||
```cpp
|
||||
/**
|
||||
* <title>
|
||||
*
|
||||
* <longer description, can be multi-line>
|
||||
*
|
||||
* @unit <the unit, e.g. m for meters>
|
||||
* @min <the minimum sane value. Can be overridden by the user>
|
||||
* @max <the maximum sane value. Can be overridden by the user>
|
||||
* @decimal <the minimum sane value. Can be overridden by the user>
|
||||
* @increment <the "ticks" in which this value will increment in the UI>
|
||||
* @reboot_required true <add this if changing the param requires a system restart.>
|
||||
* @boolean <add this for integer parameters that represent a boolean value>
|
||||
* @group <a title for parameters that form a group>
|
||||
*/
|
||||
```
|
||||
|
||||
## Publishing Parameter Metadata to a GCS
|
||||
|
||||
The parameter metadata JSON file is compiled into firmware (or hosted on the Internet), and made available to ground stations via the [MAVLink Component Metadata service](https://mavlink.io/en/services/component_information.html).
|
||||
This ensures that metadata is always up-to-date with the code running on the vehicle.
|
||||
|
||||
This process is the same as for [events metadata](../concept/events_interface.md#publishing-event-metadata-to-a-gcs).
|
||||
For more information see [PX4 Metadata (Translation & Publication)](../advanced/px4_metadata.md)
|
||||
|
||||
## Further Information
|
||||
|
||||
- [Finding/Updating Parameters](../advanced_config/parameters.md)
|
||||
- [Parameter Reference](../advanced_config/parameter_reference.md)
|
||||
- [Param implementation](https://github.com/PX4/PX4-Autopilot/blob/main/platforms/common/include/px4_platform_common/param.h#L129) (information on `.get()`, `.commit()`, and other methods)
|
||||
@@ -0,0 +1,87 @@
|
||||
# PX4 Metadata
|
||||
|
||||
PX4 uses and generates data that has associated human- and machine- readable metadata:
|
||||
|
||||
- [Parameters](../advanced_config/parameters.md) configure PX4 behaviour.
|
||||
- A parameter is represented by an ID string that maps to a value stored in PX4.
|
||||
- The associated metadata includes a description of the setting, its possible values, information about how the value might be presented (say for bitmasks).
|
||||
- [Events](../concept/events_interface.md) provide notification of events, such as reasons for a failsafe, low battery warnings, end of calibration, and so on.
|
||||
- An event is represented by an id, and is sent with a log level and arguments.
|
||||
- The associated metadata includes a message, a description and a list of arguments (including their type) of each event.
|
||||
- [Actuators](../config/actuators.md) configuration customizes the specific geometry of the vehicle, assigns actuators and motors to flight controller outputs, and tests the actuator and motor response.
|
||||
- The metadata contains information about supported vehicle geometries, a list of output drivers, and how to configure them.
|
||||
- _QGroundControl_ uses that information to dynamically build a configuration UI.
|
||||
|
||||
The metadata and metadata translations are shared with external systems, such as QGroundControl, allowing them to display information about parameters and events, and to configure vehicle geometry and actuator output mappings.
|
||||
|
||||
This topic explains how you can define metadata and help translate strings (and "just for your information", how it all works).
|
||||
|
||||
## Metadata Translation
|
||||
|
||||
Translations for PX4 metadata are done using Crowdin in the [PX4-Metadata-Translations](https://crowdin.com/project/px4-metadata-translations) project.
|
||||
For more information about working with PX4 and Crowdin see [Translation](../contribute/translation.md).
|
||||
|
||||
## Defining Metadata
|
||||
|
||||
PX4 metadata is defined in PX4 source code alongside its associated data.
|
||||
This is done either in a C/C++ comment with special markup to indicate metadata fields and their values, or using YAML files.
|
||||
|
||||
For more information see the topics for each data type:
|
||||
|
||||
- [Parameters & Configurations > Creating/Defining Parameters](../advanced/parameters_and_configurations.md#creating-defining-parameters)
|
||||
- [Events Interface](../concept/events_interface.md)
|
||||
- [Actuator Metadata](#actuator-metadata) (below)
|
||||
## Metadata Toolchain
|
||||
|
||||
The process for handling metadata is the same for all metadata types.
|
||||
|
||||
Metadata is collected into JSON files every time PX4 is built.
|
||||
|
||||
For most flight controllers (as most have enough FLASH available), the JSON file is xz-compressed and stored within the generated binary.
|
||||
The file is then shared to ground stations using the MAVLink [Component Metadata Protocol](https://mavlink.io/en/services/component_information.html).
|
||||
Using the component metadata protocol ensures that the recipient can always fetch up-to-date metadata for the code running on the vehicle.
|
||||
Events metadata is also added to the log files, allowing log analysis tools (such as Flight Review) to use the correct metadata to display events.
|
||||
|
||||
Binaries for flight controller targets with constrained memory do not store the parameter metadata in the binary, but instead reference the same data stored on `px4-travis.s3.amazonaws.com`.
|
||||
This applies, for example, to the [Omnibus F4 SD](../flight_controller/omnibus_f4_sd.md).
|
||||
The metadata is uploaded via [github CI](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/metadata.yml) for all build targets (and hence will only be available once parameters have been merged into main).
|
||||
|
||||
::: info
|
||||
You can identify memory constrained boards because they specify `CONFIG_BOARD_CONSTRAINED_FLASH=y` in their [px4board definition file](https://github.com/PX4/PX4-Autopilot/blob/main/boards/omnibus/f4sd/default.px4board).
|
||||
|
||||
If doing custom development on a FLASH-constrained board you can adjust the URL [here](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/component_information/CMakeLists.txt#L41) to point to another server.
|
||||
:::
|
||||
|
||||
The metadata on `px4-travis.s3.amazonaws.com` is used if parameter metadata is not present on the vehicle.
|
||||
It may also be used as a fallback to avoid a very slow download over a low-rate telemetry link.
|
||||
|
||||
The metadata JSON files for CI builds of `main` are also copied to the github repo: [PX4/PX4-Metadata-Translations](https://github.com/PX4/PX4-Metadata-Translations/).
|
||||
This integrates with Crowdin to get translations, which are stored in the [translated](https://github.com/PX4/PX4-Metadata-Translations/tree/main/translated) folder as xz-compressed translation files for each language.
|
||||
These are referenced by the vehicle component metadata, and are downloaded when needed.
|
||||
For more information see [PX4-Metadata-Translations](https://github.com/PX4/PX4-Metadata-Translations/) and [Component Metadata Protocol > Translation](https://mavlink.io/en/services/component_information.html#translation).
|
||||
|
||||
::: info
|
||||
The parameter XML file of the main branch is copied into the QGC source tree via CI and is used as a fallback in cases where no metadata is available via the component metadata protocol (this approach predates the existence of the component metadata protocol).
|
||||
:::
|
||||
|
||||
### Actuator Metadata
|
||||
|
||||
The following diagram shows how actuator metadata is assembled from the source code and used by QGroundControl:
|
||||
|
||||
|
||||
<!-- Source: https://docs.google.com/drawings/d/1hMQmIijdFjr21rREcXj50qz0C1b47JW0OEa6p5P231k/edit -->
|
||||
|
||||
- **Left**: the metadata is defined in `module.yml` files in different modules.
|
||||
The `control_allocator` modules defines the geometries, while each output driver defines its set of channels and configuration parameters.
|
||||
[The schema file](https://github.com/PX4/PX4-Autopilot/blob/main/validation/module_schema.yaml) documents the structure of these yaml files.
|
||||
- **Middle**: At build time, the `module.yml` files for all enabled modules for the currently built target are parsed and turned into an `actuators.json` file using the [Tools/module_config/generate_actuators_metadata.py](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/module_config/generate_actuators_metadata.py) script.
|
||||
There is also [schema file](https://github.com/mavlink/mavlink/blob/master/component_metadata/actuators.schema.json) for this.
|
||||
- **Right**: At runtime, the JSON file is requested by QGroundControl via MAVLink Component Metadata API (described above).
|
||||
|
||||
## Further Information
|
||||
|
||||
- [Parameters & Configurations](../advanced/parameters_and_configurations.md)
|
||||
- [Events Interface](../concept/events_interface.md)
|
||||
- [Translation](../contribute/translation.md)
|
||||
- [Component Metadata Protocol](https://mavlink.io/en/services/component_information.html) (mavlink.io)
|
||||
- [PX4-Metadata-Translations](https://github.com/PX4/PX4-Metadata-Translations/) (Github)
|
||||
@@ -0,0 +1,105 @@
|
||||
# Installing driver on Ubuntu for Intel RealSense R200
|
||||
|
||||
This tutorial aims to give instructions on how to install the camera driver of the Intel RealSense R200 camera head in Linux environment such that the gathered images can be accessed via the Robot Operation System (ROS).
|
||||
The RealSense R200 camera head is depicted below:
|
||||
|
||||
|
||||
|
||||
The installation of the driver package is executed on a Ubuntu operation system (OS) that runs as a guest OS in a Virtual Box.
|
||||
The specifications of the host computer where the Virtual Box is running, the Virtual Box and the guest system are given below:
|
||||
|
||||
- Host Operation System: Windows 8
|
||||
- Processor: Intel(R) Core(TM) i7-4702MQ CPU @ 2.20GHz
|
||||
- Virtual Box: Oracle VM. Version 5.0.14 r105127
|
||||
- Extensions: Extension package for Virtual Box installed (Needed for USB3 support)
|
||||
- Guest Operation System: Linux - Ubuntu 14.04.3 LTS
|
||||
|
||||
The tutorial is ordered in the following way: In a first part it is shown how to install Ubuntu 14.04 as a guest OS in the Virtual Box. In a second part is shown how to install ROS Indigo and the camera driver. The ensuing frequently used expressions have the following meaning:
|
||||
|
||||
- Virtual Box (VB): Program that runs different Virtual Machines. In this case the Oracle VM.
|
||||
- Virtual Machine (VM): The operation system that runs in the Virtual Box as a guest system. In this case Ubuntu.
|
||||
|
||||
## Installing Ubuntu 14.04.3 LTS in Virtual Box
|
||||
|
||||
- Create a new Virtual Machine (VM): Linux 64-Bit.
|
||||
- Download the iso file of Ubuntu 14.04.3 LTS: ([ubuntu-14.04.3-desktop-amd64.iso](https://ubuntu.com/download/desktop)).
|
||||
- Installation of Ubuntu:
|
||||
- During the installation procedure leave the following two options unchecked:
|
||||
- Download updates while installing
|
||||
- Install this third party software
|
||||
- After the installation you might need to enable the Virtual Box to display Ubuntu on the whole desktop:
|
||||
- Start VM Ubuntu and login, Click on **Devices->Insert Guest Additions CD image** in the menu bar of the Virtual Box.
|
||||
- Click on **Run** and enter password on the windows that pop up in Ubuntu.
|
||||
- Wait until the installation is completed and then restart.
|
||||
Now, it should be possible to display the VM on the whole desktop.
|
||||
- If a window pops up in Ubuntu that asks whether to update, reject to update at this point.
|
||||
- Enable USB 3 Controller in Virtual Box:
|
||||
- Shut down Virtual Machine.
|
||||
- Go to the settings of the Virtual Machine to the menu selection USB and choose: "USB 3.0(xHCI)".
|
||||
This is only possible if you have installed the extension package for the Virtual Box.
|
||||
- Start the Virtual Machine again.
|
||||
|
||||
## Installing ROS Indigo
|
||||
|
||||
- Follow instructions given at [ROS indigo installation guide](http://wiki.ros.org/indigo/Installation/Ubuntu):
|
||||
- Install Desktop-Full version.
|
||||
- Execute steps described in the sections "Initialize rosdep" and "Environment setup".
|
||||
|
||||
## Installing camera driver
|
||||
|
||||
- Install git:
|
||||
|
||||
```sh
|
||||
sudo apt-get install git
|
||||
```
|
||||
|
||||
- Download and install the driver:
|
||||
|
||||
- Clone [RealSense_ROS repository](https://github.com/bestmodule/RealSense_ROS):
|
||||
|
||||
```sh
|
||||
git clone https://github.com/bestmodule/RealSense_ROS.git
|
||||
```
|
||||
|
||||
- Follow instructions given in [here](https://github.com/bestmodule/RealSense_ROS/tree/master/r200_install).
|
||||
|
||||
- Press the enter button when the questions whether to install the following installation packages show up:
|
||||
|
||||
```sh
|
||||
Intel Low Power Subsystem support in ACPI mode (MFD_INTEL_LPSS_ACPI) [N/m/y/?] (NEW)
|
||||
```
|
||||
|
||||
```sh
|
||||
Intel Low Power Subsystem support in PCI mode (MFD_INTEL_LPSS_PCI) [N/m/y/?] (NEW)
|
||||
```
|
||||
|
||||
```sh
|
||||
Dell Airplane Mode Switch driver (DELL_RBTN) [N/m/y/?] (NEW)
|
||||
```
|
||||
|
||||
- The following error message that can appear at the end of the installation process should not lead to a malfunction of the driver:
|
||||
|
||||
```sh
|
||||
rmmod: ERROR: Module uvcvideo is not currently loaded
|
||||
```
|
||||
|
||||
- After the installation has completed, reboot the Virtual Machine.
|
||||
|
||||
- Test camera driver:
|
||||
|
||||
- Connect the Intel RealSense camera head with the computer with a USB3 cable that is plugged into a USB3 receptacle on the computer.
|
||||
- Click on Devices->USB-> Intel Corp Intel RealSense 3D Camera R200 in the menu bar of the Virtual Box, in order to forward the camera USB connection to the Virtual Machine.
|
||||
- Execute the file [unpacked folder]/Bin/DSReadCameraInfo:
|
||||
|
||||
- If the following error message appears, unplug the camera (physically unplug USB cable from the computer). Plug it in again + Click on Devices->USB-> Intel Corp Intel RealSense 3D Camera R200 in the menu bar of the Virtual Box again and execute again the file [unpacked folder]/Bin/DSReadCameraInfo.
|
||||
|
||||
```sh
|
||||
DSAPI call failed at ReadCameraInfo.cpp:134!
|
||||
```
|
||||
|
||||
- If the camera driver works and recognises the Intel RealSense R200, you should see specific information about the Intel RealSense R200 camera head.
|
||||
|
||||
- Installation and testing of the ROS nodlet:
|
||||
- Follow the installation instructions in the "Installation" section given [here](https://github.com/bestmodule/RealSense_ROS/blob/master/realsense_dist/2.3/doc/RealSense-ROS-R200-nodelet.md), to install the ROS nodlet.
|
||||
- Follow the instructions in the "Running the R200 nodelet" section given [here](https://github.com/bestmodule/RealSense_ROS/blob/master/realsense_dist/2.3/doc/RealSense-ROS-R200-nodelet.md), to test the ROS nodlet together with the Intel RealSense R200 camera head.
|
||||
- If everything works, the different data streams from the Intel RealSense R200 camera are published as ROS topics.
|
||||
@@ -0,0 +1,101 @@
|
||||
# RTK GNSS/GPS (PX4 Integration)
|
||||
|
||||
[Real Time Kinematic](https://en.wikipedia.org/wiki/Real_Time_Kinematic) (RTK) provides centimeter-level GPS accuracy.
|
||||
This page explains how RTK is integrated into PX4.
|
||||
|
||||
:::tip
|
||||
Instructions for _using_ RTK GNSS are provided in [Hardware > RTK GPS](../gps_compass/rtk_gps.md).
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
RTK uses measurements of the phase of the signal's carrier wave, rather than the information content of the signal.
|
||||
It relies on a single reference station to provide real-time corrections, which can work with multiple mobile stations.
|
||||
|
||||
Two RTK GNSS modules and a datalink are required to setup RTK with PX4.
|
||||
The fixed-position ground-based GPS unit is called the _Base_ and the in-air unit is called the _Rover_.
|
||||
The Base unit connects to _QGroundControl_ (via USB) and uses the datalink to stream RTCM corrections to the vehicle (using the MAVLink [GPS_RTCM_DATA](https://mavlink.io/en/messages/common.html#GPS_RTCM_DATA) message).
|
||||
On the autopilot, the MAVLink packets are unpacked and sent to the Rover unit, where they are processed to get the RTK solution.
|
||||
|
||||
The datalink should typically be able to handle an uplink rate of 300 bytes per second (see the [Uplink Datarate](#uplink-datarate) section below for more information).
|
||||
|
||||
## Supported RTK GNSS modules
|
||||
|
||||
The list of devices that we have tested can be found [in the user guide](../gps_compass/rtk_gps.md#supported-devices).
|
||||
|
||||
::: info
|
||||
Most devices come with two variants, a base and a rover.
|
||||
Make sure to select the correct variant.
|
||||
:::
|
||||
|
||||
## Automatic Configuration
|
||||
|
||||
The PX4 GPS stack automatically sets up the GPS modules to send and receive the correct messages over the UART or USB, depending on where the module is connected (to _QGroundControl_ or the autopilot).
|
||||
|
||||
As soon as the autopilot receives `GPS_RTCM_DATA` MAVLink messages, it automatically forwards the RTCM data to the attached GPS module over existing data channels (a dedicated channel for correction data is not required).
|
||||
|
||||
::: info
|
||||
The u-blox U-Center RTK module configuration tool is not needed/used!
|
||||
:::
|
||||
|
||||
::: info
|
||||
Both _QGroundControl_ and the autopilot firmware share the same [PX4 GPS driver stack](https://github.com/PX4/GpsDrivers).
|
||||
In practice, this means that support for new protocols and/or messages only need to be added to one place.
|
||||
:::
|
||||
|
||||
### RTCM messages
|
||||
|
||||
QGroundControl configures the RTK base station to output the following RTCM3.2 frames, each with 1 Hz, unless otherwise stated:
|
||||
|
||||
- **1005** - Station coordinates XYZ for antenna reference point (Base position), 0.2 Hz.
|
||||
- **1077** - Full GPS pseudo-ranges, carrier phases, Doppler and signal strength (high resolution).
|
||||
- **1087** - Full GLONASS pseudo-ranges, carrier phases, Doppler and signal strength (high resolution).
|
||||
- **1230** - GLONASS code-phase biases.
|
||||
- **1097** - Full Galileo pseudo-ranges, carrier phases, Doppler and signal strength (high resolution)
|
||||
- **1127** - Full BeiDou pseudo-ranges, carrier phases, Doppler and signal strength (high resolution)
|
||||
|
||||
## Uplink datarate
|
||||
|
||||
The raw RTCM messages from the base are packed into a MAVLink `GPS_RTCM_DATA` message and sent over the datalink.
|
||||
The maximum length of each MAVLink message is 182 bytes. Depending on the RTCM message, the MAVLink message is almost never completely filled.
|
||||
|
||||
The RTCM Base Position message (1005) is of length 22 bytes, while the others are all of variable length depending on the number of visible satellites and the number of signals from the satellite (only 1 for L1 units like M8P).
|
||||
Since at a given time, the _maximum_ number of satellites visible from any single constellation is 12, under real-world conditions, theoretically an uplink rate of 300 B/s is sufficient.
|
||||
|
||||
If _MAVLink 1_ is used, a 182-byte `GPS_RTCM_DATA` message is sent for every RTCM message, irrespective of its length.
|
||||
As a result the approximate uplink requirement is around 700+ bytes per second.
|
||||
This can lead to link saturation on low-bandwidth half-duplex telemetry modules (e.g. 3DR Telemetry Radios).
|
||||
|
||||
If _MAVLink 2_ is used then any empty space in the `GPS_RTCM_DATA message` is removed.
|
||||
The resulting uplink requirement is about the same as the theoretical value (~300 bytes per second).
|
||||
|
||||
:::tip
|
||||
PX4 automatically switches to MAVLink 2 if the GCS and telemetry modules support it.
|
||||
:::
|
||||
|
||||
MAVLink 2 must be used on low-bandwidth links for good RTK performance. Care must be taken to make sure that the telemetry chain uses MAVLink 2 throughout.
|
||||
You can verify the protocol version by using the `mavlink status` command on the system console:
|
||||
|
||||
```sh
|
||||
nsh> mavlink status
|
||||
instance #0:
|
||||
GCS heartbeat: 593486 us ago
|
||||
mavlink chan: #0
|
||||
type: 3DR RADIO
|
||||
rssi: 219
|
||||
remote rssi: 219
|
||||
txbuf: 94
|
||||
noise: 61
|
||||
remote noise: 58
|
||||
rx errors: 0
|
||||
fixed: 0
|
||||
flow control: ON
|
||||
rates:
|
||||
tx: 1.285 kB/s
|
||||
txerr: 0.000 kB/s
|
||||
rx: 0.021 kB/s
|
||||
rate mult: 0.366
|
||||
accepting commands: YES
|
||||
MAVLink version: 2
|
||||
transport protocol: serial (/dev/ttyS1 @57600)
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
# Switching State Estimators
|
||||
|
||||
This page shows you which state estimators are available and how you can switch between them.
|
||||
|
||||
:::tip
|
||||
EKF2 is the default and should be used unless you have a reason not to (in particular on vehicles with a GNSS/GPS).
|
||||
The Q-Estimator can be used if you don't have GPS, and is commonly used in [multicopter racers](../config_mc/racer_setup.md).
|
||||
:::
|
||||
|
||||
## Available Estimators
|
||||
|
||||
The available estimators are:
|
||||
|
||||
- **EKF2 attitude, position and wind states estimator** (_recommended_) - An extended Kalman filter estimating attitude, 3D position / velocity and wind states.
|
||||
- **LPE position estimator** (_deprecated_) - An extended Kalman filter for 3D position and velocity states.
|
||||
|
||||
:::warning
|
||||
LPE is deprecated.
|
||||
It works (at time of writing, in PX4 v1.14) but is no longer supported or maintained.
|
||||
:::
|
||||
|
||||
- **Q attitude estimator** - A very simple, quaternion based complementary filter for attitude.
|
||||
It does not require a GPS, magnetometer, or barometer.
|
||||
<!-- Q estimator is supported (at time of writing in PX4 v1.14). Test added in PX4-Autopilot/pull/21922 -->
|
||||
|
||||
## How to Enable Different Estimators
|
||||
|
||||
<!-- Changed in https://github.com/PX4/PX4-Autopilot/pull/22567 after v1.14 -->
|
||||
|
||||
To enable a particular estimator enable its parameter and disable the others:
|
||||
|
||||
- [EKF2_EN](../advanced_config/parameter_reference.md#EKF2_EN) - EKF2 (default/recommended)
|
||||
- [ATT_EN](../advanced_config/parameter_reference.md#ATT_EN) - Q Estimator (quaternion based attitude estimator)
|
||||
- [LPE_EN](../advanced_config/parameter_reference.md#LPE_EN) - LPE (not supported for Fixed-wing)
|
||||
|
||||
::: warning
|
||||
It is important to enable one, and only one, estimator.
|
||||
If more than one is enabled, the first to publish the UOrb topics [vehicle_attitude](../msg_docs/VehicleAttitude.md) or [vehicle_local_position](../msg_docs/VehicleLocalPosition.md) is used.
|
||||
If none are enabled then the topics are not published.
|
||||
:::
|
||||
|
||||
::: info
|
||||
For FMU-v2 (only) you will also need to build PX4 to specifically include required estimator (e.g. EKF2: `make px4_fmu-v2`, LPE: `make px4_fmu-v2_lpe`).
|
||||
This is required because FMU-v2 is too resource constrained to include both estimators.
|
||||
Other Pixhawk FMU versions include both.
|
||||
:::
|
||||
@@ -0,0 +1,88 @@
|
||||
# System Notification Tunes
|
||||
|
||||
PX4 defines a number of [standard tones/tunes](../getting_started/tunes.md) that are used to provide audio notification for important system states and problems (e.g. system startup, arming success, battery warnings, etc.)
|
||||
|
||||
Tunes are specified using strings (in [ANSI Music notation](http://artscene.textfiles.com/ansimusic/information/ansimtech.txt)) and played by code using the [tunes](https://github.com/PX4/PX4-Autopilot/tree/main/src/lib/tunes) library.
|
||||
The tunes library also contains the list of default system tunes - see [lib/tunes/tune_definition.desc](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/tunes/tune_definition.desc).
|
||||
|
||||
PX4 also has a module that can be used to play (test) the default tunes or a user defined tune.
|
||||
|
||||
This topic provides general guidance on how to create your own tunes and add to/replace the system notification tones/tunes.
|
||||
|
||||
## Creating Tunes
|
||||
|
||||
Tune strings are defined using [ANSI Music notation](http://artscene.textfiles.com/ansimusic/information/ansimtech.txt).
|
||||
|
||||
:::tip
|
||||
More information about the format can be found in [QBasic PLAY statement](https://en.wikibooks.org/wiki/QBasic/Appendix#PLAY) (Wikibooks) and has been reproduced in [tune_definition.desc](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/tunes/tune_definition.desc).
|
||||
:::
|
||||
|
||||
The easiest way to create a new tune is to use a music editor.
|
||||
This allows you to edit the music and play it back on your computer, then export it to a format that can be played by PX4.
|
||||
|
||||
ANSI music was popular in the days of ANSI BBS systems, and so the best editing tools are DOS utilities.
|
||||
On Windows, one option is to use _Melody Master_ within _Dosbox_.
|
||||
|
||||
The steps for using the software are:
|
||||
|
||||
1. Download [DosBox](http://www.dosbox.com/) and install the app
|
||||
1. Download [Melody Master](ftp://archives.thebbs.org/ansi_utilities/melody21.zip) and unzip into a new directory
|
||||
1. Open the _Dosbox_ console
|
||||
1. Mount the melody master directory in Dosbox as shown below:
|
||||
|
||||
```sh
|
||||
mount c C:\<path_to_directory\Melody21
|
||||
```
|
||||
|
||||
1. Start _Melody Master_ with the following commands
|
||||
|
||||
```sh
|
||||
c:
|
||||
start
|
||||
```
|
||||
|
||||
1. You will then have the option to click through a few screens, then press **1** to display _Melody Master_:
|
||||
|
||||
|
||||
The lower half of the screen provides helpful advice on keyboard shortcuts for using the tool (arrows for moving in stave, and numbers for selecting the note length, etc.).
|
||||
|
||||
1. When you're ready to save the music:
|
||||
- Press **F2** to give the tune a name and save it in the _/Music_ sub folder of your Melody Master installation.
|
||||
- Press **F7**, the scroll down the list of output formats on the right to get to ANSI.
|
||||
The file will be exported to the _root_ of the Melody Master directory (with the same name and a file-type specific extension).
|
||||
1. Open the file.
|
||||
The output might look like this:
|
||||
|
||||
|
||||
|
||||
1. The string that can be played in PX4 is the bit between `MNT` and `P64`: `150L1O3DL16CL32<B>C<AEL16A`
|
||||
|
||||
## Testing Tunes
|
||||
|
||||
When you're ready to try it out a new tune on PX4, use the [tune_control](../modules/modules_system.md#tune-control) library.
|
||||
For example, to test the tune we "created" above you would enter the following command on a console or shell (e.g. the [MAVLink Shell](../debug/mavlink_shell.md)):
|
||||
|
||||
```sh
|
||||
tune_control play -m "150L1O3DL16CL32<B>C<AEL16A"
|
||||
```
|
||||
|
||||
::: info
|
||||
Out of the box, the `tune_control` is only present on real hardware (not the simulator).
|
||||
:::
|
||||
|
||||
## Replacing Existing Tunes
|
||||
|
||||
Tunes are defined within [tune_definition.desc](https://github.com/PX4/PX4-Autopilot/blob/main/src/lib/tunes/tune_definition.desc).
|
||||
|
||||
If you just need to replace an existing tune, then you can replace the file in your own fork, and update the tune strings defined in `PX4_DEFINE_TUNE`.
|
||||
|
||||
## Adding a New Tune
|
||||
|
||||
TBD.
|
||||
|
||||
<!--
|
||||
|
||||
1. Assumption is that you need to define a new `PX4_DEFINE_TUNE` with its own number in the file.
|
||||
2. Need to look at how tunes are played. Problem for another day.
|
||||
|
||||
-->
|
||||
Reference in New Issue
Block a user