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>
2026-10-20 23:13:34 +08:00 · 2025-03-13 16:08:27 +11:00
parent 8e6d2ebe4a
commit 88d623bedb
5176 changed files with 558771 additions and 2 deletions
@@ -0,0 +1 @@
+<Redirect to="../robotics/#dronekit" />
@@ -0,0 +1,74 @@
+# Drone Apps & APIs
+
+Drone APIs let you write code to control and integrate with PX4-powered vehicles, without having to understand intimate details of the vehicle and flight stack, or having to think about safety-critical behaviour.
+
+PX4는 <a href="https://mavsdk.mavlink.io/">MAVSDK</a> 및 <a href="../ros/README.md">ROS</a>를 포함하는 로봇 공학 API와 함께 사용할 수 있습니다.
+Drone APIs allow you to do this using high level instructions in your programming language of choice, and the code can then run on-vehicle in a [companion computer](../companion_computer/index.md), or from a ground station.
+Under the the hood the APIs communicate with PX4 using [MAVLink](../middleware/mavlink.md) or [uXRCE-DDS](../middleware/uxrce_dds.md).
+
+PX4 supports the following SDKs/Robotics tools:
+
+- [MAVSDK](../robotics/mavsdk.md)
+- [ROS 2](../ros/index.md)
+- [ROS 1](../ros/index.md)
+
+## What API should I use?
+
+We recommend using MAVSDK where possible, primarily because it is more intuitive and easier to learn, and can run on more operating systems and less performant-hardware.
+
+You may prefer ROS if you already know how to use it, or if you want to leverage pre-existing integrations (for example computer vision tasks).
+More generally, ROS is likely to be a better choice for tasks that require very low latency or a deeper integration with PX4 than is provided by MAVLink.
+
+The main difference are:
+
+- **MAVSDK:**
+  - Intuitive and optimised for drones, with a small learning curve and easy setup.
+  - You can write apps in C++, Python, Swift, Java, Go, and more.
+  - Runs on resource-constrained hardware
+  - Runs on broad range of OSs, including Android, Linux, Windows.
+  - Communicates over MAVLink.
+    - Stable and widely supported.
+    - Limited to MAVLink services - needed information may not be exposed.
+    - Latency may be too high for some use cases.
+- **ROS 2**
+  - General-purpose robotics API that has been extended to support drone integration:
+    - Conceptually not as well optimised for drones as MAVSDK
+    - Significant learning curve
+  - Many pre-existing libraries: useful for code-reuse.
+  - Supports C++ and Python libraries
+  - Runs on Linux
+  - ROS 2 is the latest version, which connects via XRCE-DDS.
+    - DDS interface layer allows deep integration into any aspect of PX4 that is exposed as a UORB topic (almost everything).
+    - Can provide much lower latency.
+    - Still under development:
+      - At time of writing requires a deeper understanding of PX4 than ROS 1.
+      - Message interface with PX4 not stable/maintained across ROS and PX4 releases.
+
+## Deprecated APIs
+
+### ROS 1
+
+While not strictly deprecated, ROS 1 is at its final LTS Release version "Noetic Ninjemys", which reaches end-of-life in May 2025.
+That means no new features or bug fixes will be provided, and even security updates will cease in 2025.
+
+ROS 1 still "works" on PX4 because it uses MAVROS, a MAVLINK-ROS abstraction as an integration layer.
+This means that ROS 1 has all the limitations of MAVLink, such as a higher latency and a small API surface (and also the benefits, such as a stable interface).
+
+All PX4 investment in ROS is going towards a deep integration with ROS 2.
+This will essentially allow ROS 2 applications to be close to indistinguishable from code running in PX4 itself.
+
+:::tip
+Use ROS 2 for new projects.
+Upgrade to ROS 2 for existing projects as soon as possible.
+:::
+
+### DroneKit PX4 통신
+
+DroneKit-Python is a MAVLink API written in Python.
+It is not optimised for use with PX4, and has not be maintained for some years.
+Legacy docs for using PX4 and DroneKit can be found here: [PX4 v1.12 > DroneKit](https://docs.px4.io/v1.12/en/robotics/dronekit.html).
+
+:::tip
+[MAVSDK](https://mavsdk.mavlink.io/) is the recommended MAVLink API for use with PX4.
+It is better in almost every way: features, speed, programming language support, maintenance, and so on.
+:::
@@ -0,0 +1,19 @@
+# MAVSDK
+
+[MAVSDK](https://mavsdk.mavlink.io/main/en/index.html) is a MAVLink SDK that allows you to communicate with MAVLink systems such as drones, cameras or ground systems.
+
+The SDK provides interface libraries for various programming languages, with a simple API for managing one or more vehicles.
+It provides programmatic access to vehicle information and telemetry, and control over missions, movement and other operations.
+It can also be used to communicate with MAVLink components, such as cameras, gimbals, and other hardware.
+
+MAVSDK libraries can be used onboard a drone on a companion computer, or on a ground station or mobile device, and can run on Linux, macOS, Windows, Android, and iOS.
+
+:::info
+MAVSDK is easier to learn than [ROS 2](../ros2/index.md) and has a more stable API.
+It is recommended for communicating from ground stations, for relatively low bandwidth command/control from a companion computer, and for integrating with onboard components that do not have high bandwidth requirements, such as cameras and gimbals.
+
+ROS is recommended for high-bandwidth onboard communication, to provide features such as obstacle avoidance that require higher rate messages and that can leverage existing ROS and computer vision libraries..
+:::
+
+The SDK can also be used to write MAVLink "server" code: the side of a MAVLink communication that is normally implemented by an autopilot, MAVLink camera, or other component.
+This can be used to create a MAVLink API for components running on a companion computer, such as a camera API interface for a native camera connected to the computer.