From cc19ab381f5dba9c56007a2445ab9ecfec3d5359 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 29 Jan 2025 12:21:12 +1100 Subject: [PATCH] Fix notes tips warnings in docs (#2501) * fix notes * Fix tips * Fix warning * catch a few outliers --- docs/en/cpp/api_changes.md | 11 ++-- docs/en/cpp/contributing/documentation.md | 4 +- docs/en/cpp/contributing/plugins.md | 60 ++++++++++++------- docs/en/cpp/contributing/release.md | 4 +- docs/en/cpp/examples/autopilot_server.md | 12 ++-- docs/en/cpp/examples/fly_mission.md | 6 +- docs/en/cpp/examples/follow_me.md | 14 +++-- docs/en/cpp/examples/index.md | 39 ++++++++---- docs/en/cpp/examples/offboard_velocity.md | 6 +- docs/en/cpp/examples/takeoff_and_land.md | 14 +++-- .../examples/transition_vtol_fixed_wing.md | 6 +- docs/en/cpp/guide/build.md | 19 +++--- docs/en/cpp/guide/build_docs.md | 12 ++-- docs/en/cpp/guide/build_mavsdk_server.md | 9 ++- docs/en/cpp/guide/code_style.md | 6 +- docs/en/cpp/guide/connections.md | 8 ++- docs/en/cpp/guide/dev_logging.md | 5 +- docs/en/cpp/guide/follow_me.md | 18 ++++-- docs/en/cpp/guide/general_usage.md | 6 +- docs/en/cpp/guide/installation.md | 6 +- docs/en/cpp/guide/missions.md | 43 ++++++++----- docs/en/cpp/guide/offboard.md | 16 +++-- docs/en/cpp/guide/system_information.md | 18 ++++-- docs/en/cpp/guide/taking_off_landing.md | 46 ++++++++++---- docs/en/cpp/guide/telemetry.md | 20 +++++-- docs/en/cpp/guide/test.md | 17 ++++-- docs/en/cpp/guide/toolchain.md | 10 +++- docs/en/cpp/guide/using_plugins.md | 10 +++- docs/en/cpp/guide/vtol.md | 6 +- docs/en/cpp/quickstart.md | 10 +++- docs/en/cpp/server_plugins.md | 6 +- docs/en/faq.md | 16 +++-- docs/en/python/quickstart.md | 12 +++- 33 files changed, 332 insertions(+), 163 deletions(-) diff --git a/docs/en/cpp/api_changes.md b/docs/en/cpp/api_changes.md index 474a0e545..65df63fa1 100644 --- a/docs/en/cpp/api_changes.md +++ b/docs/en/cpp/api_changes.md @@ -17,7 +17,9 @@ Individual parts of the number are iterated when the: This means that breaking changes to the API result in a bump of the major version number (e.g. 1.4.3 to 2.0.0). -> **note**: bumping of the major version is unrelated to the stability of the library. E.g. v2.0.0 is not by definition more stable than v1.4.18. It just means that the API has changed with v2. As development is carried on, stability is likely increasing whenever the minor or patch versions increase as incremental fixes are added. +::: info +Bumping of the major version is unrelated to the stability of the library. E.g. v2.0.0 is not by definition more stable than v1.4.18. It just means that the API has changed with v2. As development is carried on, stability is likely increasing whenever the minor or patch versions increase as incremental fixes are added. +::: ## v2 @@ -37,8 +39,9 @@ New instantiation: Mavsdk mavsdk{Mavsdk::Configuration{Mavsdk::ComponentType::GroundStation}}; ``` -**Note:** +::: info It is still possible to change the configuration later (although not recommended) using `Mavsdk::set_configuration(...)`. +::: **Rationale:** @@ -48,9 +51,9 @@ For instance, in the case where MAVSDK is used on the companion computer, the au Also, having to set the default makes it less likely to misconfigure the overall integration and end up with several components that conflict. -**Note:** +::: info It is also possible to set the sysid/compid directly, just check out the API of [Mavsdk::Configuration](cpp/api_reference/classmavsdk_1_1_mavsdk_1_1_configuration.md). - +::: ### Subscription API diff --git a/docs/en/cpp/contributing/documentation.md b/docs/en/cpp/contributing/documentation.md index 4bd6662f5..52bc5ec2b 100644 --- a/docs/en/cpp/contributing/documentation.md +++ b/docs/en/cpp/contributing/documentation.md @@ -4,7 +4,9 @@ Making quick fixes to existing text or raising issues is very easy. More complicated changes will require you to set up the [Gitbook toolchain](https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md). If you want to help, [get in touch](../../index.md#getting-help). -> **Tip** You will need a [Github](https://github.com/) login to make and submit changes to this guide. +::: tip +You will need a [Github](https://github.com/) login to make and submit changes to this guide. +::: ## Overview diff --git a/docs/en/cpp/contributing/plugins.md b/docs/en/cpp/contributing/plugins.md index bc86584c4..ea09fb0ad 100644 --- a/docs/en/cpp/contributing/plugins.md +++ b/docs/en/cpp/contributing/plugins.md @@ -122,10 +122,12 @@ message SetReturnToLaunchAltitudeResponse { } ``` -> **Note** Requests can defined SYNC, ASYNC, or BOTH using `option (mavsdk.options.async_type) = ...;`. - The choice depends on the functionality that is being implemented and how it would generally be used. - There are no hard rules, it's something that makes sense to be discussed one by one in a pull request. - The default implementation is `BOTH`. +::: info +Requests can defined SYNC, ASYNC, or BOTH using `option (mavsdk.options.async_type) = ...;`. +The choice depends on the functionality that is being implemented and how it would generally be used. +There are no hard rules, it's something that makes sense to be discussed one by one in a pull request. +The default implementation is `BOTH`. +::: #### Subscriptions: @@ -144,11 +146,15 @@ message PositionResponse { } ``` -> **Note** Subscriptions also can defined SYNC, ASYNC, or BOTH using `option (mavsdk.options.async_type) = ...;`. - The sync implementation of a subscription is just a getter for the last received value. +::: info +Subscriptions also can defined SYNC, ASYNC, or BOTH using `option (mavsdk.options.async_type) = ...;`. +The sync implementation of a subscription is just a getter for the last received value. +::: -> **Note** Subscriptions can be defined finite using `option (mavsdk.options.is_finite) = true;`. - This means that the stream of messages will end at some point instead of continuing indefinitely. An example would be progress updates about a calibration which eventually finishes. +::: info +Subscriptions can be defined finite using `option (mavsdk.options.is_finite) = true;`. +This means that the stream of messages will end at some point instead of continuing indefinitely. An example would be progress updates about a calibration which eventually finishes. +::: ### Add API to proto @@ -191,10 +197,12 @@ Once the proto file has been created, you can generate all files required for th tools/fix_style.sh . ``` -> **Note** the files `my_new_plugin.h` and `my_new_plugin.cpp` are generated and overwritten every time the script is run. - However, the files `my_new_plugin_impl.h` and `my_new_plugin_impl.cpp` are only generated once. - To re-generate them, delete them and run the script again. - This approach is used to prevent the script from overwriting your local changes. +::: info +The files `my_new_plugin.h` and `my_new_plugin.cpp` are generated and overwritten every time the script is run. +However, the files `my_new_plugin_impl.h` and `my_new_plugin_impl.cpp` are only generated once. +To re-generate them, delete them and run the script again. +This approach is used to prevent the script from overwriting your local changes. +::: ### Actually implement MAVLink messages @@ -277,7 +285,9 @@ Most of the existing plugins do not have unit tests, because we do not yet have the ability to [mock MAVLink communications](https://github.com/mavlink/MAVSDK/issues/148) (needed to test most plugins). Unit tests are therefore considered optional! -> **Tip** Comprehensive integration tests should be written instead, with the simulator providing appropriate MAVLink messages. +::: tip +Comprehensive integration tests should be written instead, with the simulator providing appropriate MAVLink messages. +::: #### Adding Unit Tests {#adding_unit_tests} @@ -308,9 +318,9 @@ All tests in a file should share the same test-case name (the first argument to MAVSDK provides the `integration_tests_runner` application for running the integration tests and some helper code to make it easier to log tests and run them against the simulator. -> **Tip** Check out the [Google Test Primer](https://google.github.io/googletest/primer.html) -> and the [integration_tests](https://github.com/mavlink/MAVSDK/tree/main/src/integration_tests) -> for our existing plugins to better understand how to write your own! +::: tip +Check out the [Google Test Primer](https://google.github.io/googletest/primer.html) and the [integration_tests](https://github.com/mavlink/MAVSDK/tree/main/src/integration_tests) for our existing plugins to better understand how to write your own! +::: #### Adding Integration Tests @@ -342,15 +352,19 @@ add_executable(integration_tests_runner The main MAVSDK-specific functionality is provided by [integration_test_helper.h](https://github.com/mavlink/MAVSDK/blob/main/src/integration_tests/integration_test_helper.h). This provides access to the [Plugin/Test Logger](../guide/dev_logging.md) and a shared test class `SitlTest` for setting up and tearing down the PX4 simulator. -> **Note** All tests running against SITL can be declared using `TEST_F` and have a first argument `SitlTest` as shown. - This is required in order to use the shared class to set up and tear down the simulator between tests. +::: info +All tests running against SITL can be declared using `TEST_F` and have a first argument `SitlTest` as shown. +This is required in order to use the shared class to set up and tear down the simulator between tests. +::: For reference inspect the [existing integration tests](https://github.com/mavlink/MAVSDK/blob/main/src/integration_tests). ## Example Code -> **Note** It is quicker and easier to write and modify [integration tests](#integration_tests) than examples. -> Do not write example code until the plugin has been accepted! +::: info +It is quicker and easier to write and modify [integration tests](#integration_tests) than examples. +Do not write example code until the plugin has been accepted! +::: A simple example should be written that demonstrates basic usage of its API by 3rd parties. The example need not cover all functionality, but should demonstrate enough that developers can see how it is used and how the example might be extended. @@ -364,8 +378,10 @@ Where possible examples should demonstrate realistic use cases such that the cod The public API must be fully documented using the proto files. -> **Tip** The in-source comments will be compiled to markdown and included in the [API Reference](../api_reference/index.md). -> The process is outlined in [Documentation > API Reference](documentation.md#api-reference). +::: tip +The in-source comments will be compiled to markdown and included in the [API Reference](../api_reference/index.md). +The process is outlined in [Documentation > API Reference](documentation.md#api-reference). +::: Internal/implementation classes need not be documented, but should be written using expressive naming of variables and functions to help the reader. Anything unexpected or special however warrants an explanation as a comment. diff --git a/docs/en/cpp/contributing/release.md b/docs/en/cpp/contributing/release.md index b869ff150..4e5f4b1d9 100644 --- a/docs/en/cpp/contributing/release.md +++ b/docs/en/cpp/contributing/release.md @@ -2,7 +2,9 @@ These are the instructions on how to get a release out the door. -> **Note** The idea is of course to automate this as much as possible! +::: info +The idea is of course to automate this as much as possible! +::: ## MAVSDK part diff --git a/docs/en/cpp/examples/autopilot_server.md b/docs/en/cpp/examples/autopilot_server.md index e2490dfa8..766d27bb8 100644 --- a/docs/en/cpp/examples/autopilot_server.md +++ b/docs/en/cpp/examples/autopilot_server.md @@ -3,8 +3,10 @@ The [Autopilot Server](https://github.com/mavlink/MAVSDK/tree/main/examples/autopilot_server) example creates two instances of MAVSDK, representing a client (GCS) and a server (Vehicle). The MAVSDK instances communicates with each other via UDP transmitting telemetry, publishing parameters, missions and takeoff commands. -> **Note** This example shows how to use [MAVSDK Server Plugins](../server_plugins.md)! -> This is a good starting point if you are looking to implement MAVLink services to a non-MAVLink compatible system. +::: info +This example shows how to use [MAVSDK Server Plugins](../server_plugins.md)! +This is a good starting point if you are looking to implement MAVLink services to a non-MAVLink compatible system. +::: ## Running the Example {#run_example} @@ -13,8 +15,10 @@ The example is built and run in the normal way ([as described here](../examples/ The example terminal output should be similar to that shown below: -> **Note** This is from a debug build of the SDK. - A release build will omit the "Debug" messages. +::: info +This is from a debug build of the SDK. +A release build will omit the "Debug" messages. +::: ``` $ ./autopilot_server diff --git a/docs/en/cpp/examples/fly_mission.md b/docs/en/cpp/examples/fly_mission.md index c98473176..3a352494a 100644 --- a/docs/en/cpp/examples/fly_mission.md +++ b/docs/en/cpp/examples/fly_mission.md @@ -11,8 +11,10 @@ The example is built and run in the normal way ([as described here](../examples/ The example terminal output should be similar to that shown below: -> **Note** This is from a debug build of the SDK. - A release build will omit the "Debug" messages. +::: info +This is from a debug build of the SDK. +A release build will omit the "Debug" messages. +::: ``` $ ./fly_mission udp://:14540 diff --git a/docs/en/cpp/examples/follow_me.md b/docs/en/cpp/examples/follow_me.md index 6514ce2cb..afed0ec00 100644 --- a/docs/en/cpp/examples/follow_me.md +++ b/docs/en/cpp/examples/follow_me.md @@ -5,9 +5,11 @@ It shows how to send the drone both the current position of the target (`FollowM ![Follow Me QGC Screenshot](../../../assets/examples/follow_me/follow_me_example_qgc.jpg) -> **Note** A real application using this API will get the position information from the underlying operating system. - The example uses a fake position source (`FakeLocationProvider`) to enable it to be run on computers that do not have position information. - The `FakeLocationProvider` emulates the typical usage of common positioning APIs used in Android, Linux and iPhone. +::: info +A real application using this API will get the position information from the underlying operating system. +The example uses a fake position source (`FakeLocationProvider`) to enable it to be run on computers that do not have position information. +The `FakeLocationProvider` emulates the typical usage of common positioning APIs used in Android, Linux and iPhone. +::: ## Running the Example {#run_example} @@ -25,8 +27,10 @@ Otherwise the example is built and run in the normal way ([as described here](.. The example terminal output should be similar to that shown below: -> **Note** This is from a debug build of the SDK. - A release build will omit the "Debug" messages. +::: info +This is from a debug build of the SDK. +A release build will omit the "Debug" messages. +::: ``` $ ./follow_me udp://:14540 diff --git a/docs/en/cpp/examples/index.md b/docs/en/cpp/examples/index.md index 9df3e8820..f604c9201 100644 --- a/docs/en/cpp/examples/index.md +++ b/docs/en/cpp/examples/index.md @@ -1,6 +1,8 @@ # C++ Examples -> **Tip** Information about *writing* example code is covered in the [Contributing > Writing Plugins](../contributing/plugins.md) (*plugin developers* should initially create [integration tests](../contributing/plugins.md#integration_tests) rather than examples for new code). +::: tip +Information about *writing* example code is covered in the [Contributing > Writing Plugins](../contributing/plugins.md) (*plugin developers* should initially create [integration tests](../contributing/plugins.md#integration_tests) rather than examples for new code). +::: This section contains examples showing how to use MAVSDK. @@ -23,16 +25,20 @@ Example | Description The examples are "largely" built and run in the same way, as described in the following section (any exceptions are covered in the page for the associated example). -> **Warning** Some of the examples define flight behaviour relative to the default home position in the simulator (e.g. [Fly Mission](../examples/fly_mission.md)). - Care should be taken if using them on a real vehicle. +::: warning +Some of the examples define flight behaviour relative to the default home position in the simulator (e.g. [Fly Mission](../examples/fly_mission.md)). +Care should be taken if using them on a real vehicle. +::: ## Trying the Examples {#trying_the_examples} The easiest way to test the examples is to use a [simulated PX4 vehicle](https://docs.px4.io/master/en/simulation/) that is running on the same computer. First start PX4 in SITL (Simulation), optionally start *QGroundControl* to observe the vehicle, then build and run the example code. -> **Note** The simulator broadcasts to the standard PX4 UDP port for connecting to offboard APIs (14540). - The examples connect to this port using either [add_any_connection()](../api_reference/classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1a405041a5043c610c86540de090626d97) or [add_udp_connection()](../api_reference/classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1aa43dfb00d5118d26ae5aabd0f9ba56b2). +::: info +The simulator broadcasts to the standard PX4 UDP port for connecting to offboard APIs (14540). +The examples connect to this port using either [add_any_connection()](../api_reference/classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1a405041a5043c610c86540de090626d97) or [add_udp_connection()](../api_reference/classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1aa43dfb00d5118d26ae5aabd0f9ba56b2). +::: ### Setting up a Simulator @@ -40,8 +46,10 @@ First start PX4 in SITL (Simulation), optionally start *QGroundControl* to obser PX4 supports a [number of simulators](https://docs.px4.io/master/en/simulation/). In order to set up the [jMAVSim](https://docs.px4.io/master/en/simulation/jmavsim.html) or [Gazebo](https://docs.px4.io/master/en/simulation/gazebo.html) simulator, you can simply follow the standard PX4 toolchain setup instructions for [macOS](https://docs.px4.io/master/en/dev_setup/dev_env_mac.html) or [Ubuntu Linux](https://docs.px4.io/master/en/dev_setup/dev_env_linux_ubuntu.html). -> **Note** JMAVSim can only be used to simulate multicopters. - Gazebo additionally supports a number of [other vehicles](https://docs.px4.io/master/en/simulation/gazebo.html#html#running-the-simulation) (e.g. VTOL, Rovers, fixed-wing etc.). +::: info +JMAVSim can only be used to simulate multicopters. +Gazebo additionally supports a number of [other vehicles](https://docs.px4.io/master/en/simulation/gazebo.html#html#running-the-simulation) (e.g. VTOL, Rovers, fixed-wing etc.). +::: After running a standard installation, a simulation can be started from the PX4 **/Firmware** directory using the command: * Multicopter (jMAVSim): `make px4_sitl jmavsim` @@ -71,10 +79,13 @@ cmake -Bbuild -H. cmake --build build -j4 ``` -> **Note** if MAVSDK is installed locally (e.g. on Windows) you need to pass the location to cmake: -> ``` -> cmake -Bbuild -DCMAKE_PREFIX_PATH=wherever_mavsdk_is_locally_installed -> ``` +::: info +if MAVSDK is installed locally (e.g. on Windows) you need to pass the location to cmake: + +``` +cmake -Bbuild -DCMAKE_PREFIX_PATH=wherever_mavsdk_is_locally_installed +``` +::: ### Running the Examples {#running_the_examples} @@ -91,8 +102,10 @@ For Windows you would run the following (from the **\build\Debug\** directory): build\Debug\takeoff_and_land.exe udp://:14540 ``` -> **Tip** Most examples will create a binary with the same name as the example. -> The name that is used is specified in the **CMakeLists.txt** file as the first value in the call to `add_executable()`. +::: tip +Most examples will create a binary with the same name as the example. +The name that is used is specified in the **CMakeLists.txt** file as the first value in the call to `add_executable()`. +::: If you have already started the simulation the example code should connect to PX4, and you will be able to observe behaviour through the SDK terminal, SITL terminal, and/or *QGroundControl*. diff --git a/docs/en/cpp/examples/offboard_velocity.md b/docs/en/cpp/examples/offboard_velocity.md index 443c084a1..f3924afb4 100644 --- a/docs/en/cpp/examples/offboard_velocity.md +++ b/docs/en/cpp/examples/offboard_velocity.md @@ -11,8 +11,10 @@ The example is built and run [as described here](../examples/index.md#trying_the The example terminal output should be similar to that shown below: -> **Note** This is from a debug build of the SDK. - A release build will omit the "Debug" messages. +::: info +This is from a debug build of the SDK. +A release build will omit the "Debug" messages. +::: ``` $ ./offboard udp://:14540 diff --git a/docs/en/cpp/examples/takeoff_and_land.md b/docs/en/cpp/examples/takeoff_and_land.md index 0d8c2a48e..8a81c45c5 100644 --- a/docs/en/cpp/examples/takeoff_and_land.md +++ b/docs/en/cpp/examples/takeoff_and_land.md @@ -6,7 +6,9 @@ It sets up a UDP connection, waits for a vehicle (system) to appear, arms it, an After a short wait the vehicle lands. While flying the vehicle receives telemetry. The example is implemented in C++ (only). -> **Tip** The full source code for the example [can be found here](https://github.com/mavlink/MAVSDK/tree/main/examples/takeoff_land). +::: tip +The full source code for the example [can be found here](https://github.com/mavlink/MAVSDK/tree/main/examples/takeoff_land). +::: ## Running the Example {#run_example} @@ -14,8 +16,10 @@ The example is built and run [as described here](../examples/index.md#trying_the The example terminal output should be similar to that shown below: -> **Note** This is from a debug build of the SDK. - A release build will omit the "Debug" messages. +::: info +This is from a debug build of the SDK. +A release build will omit the "Debug" messages. +::: ```sh $ ./takeoff_and_land udp://:14540 @@ -57,7 +61,9 @@ Finished... ## Source code {#source_code} -> **Tip** The full source code for the example [can be found on Github here](https://github.com/mavlink/MAVSDK/tree/main/examples/takeoff_and_land). +::: tip +The full source code for the example [can be found on Github here](https://github.com/mavlink/MAVSDK/tree/main/examples/takeoff_and_land). +::: - [CMakeLists.txt](https://github.com/mavlink/MAVSDK/blob/main/examples/takeoff_and_land/CMakeLists.txt) - [takeoff_and_land.cpp](https://github.com/mavlink/MAVSDK/blob/main/examples/takeoff_and_land/takeoff_and_land.cpp) diff --git a/docs/en/cpp/examples/transition_vtol_fixed_wing.md b/docs/en/cpp/examples/transition_vtol_fixed_wing.md index aeda38be6..1bfb9c090 100644 --- a/docs/en/cpp/examples/transition_vtol_fixed_wing.md +++ b/docs/en/cpp/examples/transition_vtol_fixed_wing.md @@ -10,8 +10,10 @@ This example shows how you can use the SDK [Action](../api_reference/classmavsdk The example must be run against a VTOL aircraft (simulated or otherwise). Otherwise the example is built and run [in the standard way](../examples/index.md#trying_the_examples). -> **Tip** Instructions for running the Gazebo simulator for a standard VTOL can be found here: [PX4 Development Guide > Gazebo Simulation](https://docs.px4.io/master/en/simulation/gazebo.html#standard-vtol). - jMAVSim does not support VTOL simulation. +::: tip +Instructions for running the Gazebo simulator for a standard VTOL can be found here: [PX4 Development Guide > Gazebo Simulation](https://docs.px4.io/master/en/simulation/gazebo.html#standard-vtol). +jMAVSim does not support VTOL simulation. +::: The example terminal output for a debug build of the SDK should be similar to that shown below (a release build will omit the "Debug" messages): diff --git a/docs/en/cpp/guide/build.md b/docs/en/cpp/guide/build.md index d7311570c..9c0e7a3ed 100644 --- a/docs/en/cpp/guide/build.md +++ b/docs/en/cpp/guide/build.md @@ -163,9 +163,11 @@ or run in a command prompt with admin privileges on Windows, or using `runas`: runas cmake --build build/default --target install ``` -> **Warning** Make sure to prevent conflicts between libraries installed in your system. -> The mavsdk library installed via a .deb or .rpm file will be installed in `/usr/` while the built library will be installed in `/usr/local`. -> It's recommended to only have one installed at any time to prevent conflicts. +::: warning +Make sure to prevent conflicts between libraries installed in your system. +The mavsdk library installed via a .deb or .rpm file will be installed in `/usr/` while the built library will be installed in `/usr/local`. +It's recommended to only have one installed at any time to prevent conflicts. +::: ### Local Install {#sdk_local_install} @@ -177,10 +179,13 @@ cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=install -Bbuild/default cmake --build build/default --target install ``` -> **Tip** If you already have run *cmake* without setting `CMAKE_INSTALL_PREFIX`, you may need to clean the build first: - ```sh - rm -rf build/default - ``` +::: tip +If you already have run *cmake* without setting `CMAKE_INSTALL_PREFIX`, you may need to clean the build first: + +```sh +rm -rf build/default +``` +::: ## Troubleshooting diff --git a/docs/en/cpp/guide/build_docs.md b/docs/en/cpp/guide/build_docs.md index a4e521ff8..2c64e4411 100644 --- a/docs/en/cpp/guide/build_docs.md +++ b/docs/en/cpp/guide/build_docs.md @@ -13,9 +13,11 @@ rm -rf tools/docs # Remove previous docs ``` The files are created in `/install/docs/markdown`. -> **Note** Extracting the API reference does not yet work automatically on Windows. +::: info +Extracting the API reference does not yet work automatically on Windows. +::: - -> **Note** The *generate_docs.sh* script [builds the library](build.md), installs it locally to **/install**, and then uses *DOxygen* to create XML documentation in **/install/docs/xml**. -> The [generate_markdown_from_doxygen_xml.py](https://github.com/mavlink/MAVSDK/blob/main/tools/generate_markdown_from_doxygen_xml.py) script -> is then run on all files in the */xml* directory to generate markdown files in **/install/docs/markdown**. +::: info +The *generate_docs.sh* script [builds the library](build.md), installs it locally to **/install**, and then uses *DOxygen* to create XML documentation in **/install/docs/xml**. +The [generate_markdown_from_doxygen_xml.py](https://github.com/mavlink/MAVSDK/blob/main/tools/generate_markdown_from_doxygen_xml.py) script is then run on all files in the */xml* directory to generate markdown files in **/install/docs/markdown**. +::: diff --git a/docs/en/cpp/guide/build_mavsdk_server.md b/docs/en/cpp/guide/build_mavsdk_server.md index 13da9f2e5..42c4c34a3 100644 --- a/docs/en/cpp/guide/build_mavsdk_server.md +++ b/docs/en/cpp/guide/build_mavsdk_server.md @@ -4,7 +4,9 @@ Language wrappers for MAVSDK other than C++ connect to the MAVSDK C++ core using For more information about the architecture, also see [how the auto-generation works](../contributing/autogen.md). -> **Note** It is generally recommended to use pre-built binaries of mavsdk_server from the [releases page](https://github.com/mavlink/MAVSDK/releases), however, if needed, it can also be built manually from source as described below. +::: info +It is generally recommended to use pre-built binaries of mavsdk_server from the [releases page](https://github.com/mavlink/MAVSDK/releases), however, if needed, it can also be built manually from source as described below. +::: ## Requirements @@ -24,7 +26,10 @@ cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DBUILD_MAVSDK_SERVER=O cmake --build build/default -j8 ``` -> **Note:** there is no proper support for the Apple M1 chip yet. One blocker is that there is currently no M1 hardware in GitHub Actions CI available. +::: info +There is no proper support for the Apple M1 chip yet. +One blocker is that there is currently no M1 hardware in GitHub Actions CI available. +::: ## Build on Windows diff --git a/docs/en/cpp/guide/code_style.md b/docs/en/cpp/guide/code_style.md index 36be2ce05..8990acb0e 100644 --- a/docs/en/cpp/guide/code_style.md +++ b/docs/en/cpp/guide/code_style.md @@ -2,8 +2,10 @@ This topic contains the C++ formatting and coding guidelines for MAVSDK. -> **Note** These guidelines are not written in stone! -> [Start a discussion](../../index.md#getting-help) if you have suggestions for improvement \(the project will consider anything other than "matters of personal taste"\). +::: info +These guidelines are not written in stone! +[Start a discussion](../../index.md#getting-help) if you have suggestions for improvement \(the project will consider anything other than "matters of personal taste"\). +::: ## Formatting and White Space diff --git a/docs/en/cpp/guide/connections.md b/docs/en/cpp/guide/connections.md index 3518598b6..b6466b3fe 100644 --- a/docs/en/cpp/guide/connections.md +++ b/docs/en/cpp/guide/connections.md @@ -65,9 +65,11 @@ if (connection_result != ConnectionResult::Success) { } ``` -> **Note** The connection string used above (`udp://:14540`) is to the [standard PX4 UDP port](https://docs.px4.io/master/en/simulation/#default-px4-mavlink-udp-ports) for off-board APIs (14540). - This is the normal/most common way for offboard APIs to connect to PX4 over WiFi. - The standard way to talk to a ground station (e.g. QGC is on port 14550). +::: info +The connection string used above (`udp://:14540`) is to the [standard PX4 UDP port](https://docs.px4.io/master/en/simulation/#default-px4-mavlink-udp-ports) for off-board APIs (14540). +This is the normal/most common way for offboard APIs to connect to PX4 over WiFi. +The standard way to talk to a ground station (e.g. QGC is on port 14550). +::: #### Behave like a client diff --git a/docs/en/cpp/guide/dev_logging.md b/docs/en/cpp/guide/dev_logging.md index db70343fa..29cc1b16b 100644 --- a/docs/en/cpp/guide/dev_logging.md +++ b/docs/en/cpp/guide/dev_logging.md @@ -8,7 +8,10 @@ Basic [message logging](#message_logging) can be enabled by building with a spec The API methods display a custom message, prepending a timestamp and the type of log message (e.g. debug) and appending the origin of the message (file and line number). -> **Tip** The API should be considered "internal". It is not exported, or intended, for use in SDK apps (and we do not commit to maintaining compatibility in future versions). +::: tip +The API should be considered "internal". +It is not exported, or intended, for use in SDK apps (and we do not commit to maintaining compatibility in future versions). +::: ### Usage diff --git a/docs/en/cpp/guide/follow_me.md b/docs/en/cpp/guide/follow_me.md index a09df21fe..ffb4d5ec9 100644 --- a/docs/en/cpp/guide/follow_me.md +++ b/docs/en/cpp/guide/follow_me.md @@ -9,14 +9,18 @@ Applications must get target position information from the underlying platform ( - Apple: [Core Location Framework](https://developer.apple.com/documentation/corelocation) - Windows: [Windows.Devices.Geolocation](https://docs.microsoft.com/en-us/uwp/api/Windows.Devices.Geolocation) -> **Warning** Running *QGroundControl* at the same time as the SDK *Follow Me* may result in unpredictable behaviour as both send position updates. -> You **must** ensure that *GSC Position Streaming* is disabled. -> Use the latest *QGC Daily Build* and ensure that the **[Application Setting > General](https://docs.qgroundcontrol.com/en/SettingsView/General.html) > Miscellaneous > Stream GCS Position** is set to *Never*. +::: warning +Running *QGroundControl* at the same time as the SDK *Follow Me* may result in unpredictable behaviour as both send position updates. +You **must** ensure that *GSC Position Streaming* is disabled. +Use the latest *QGC Daily Build* and ensure that the **[Application Setting > General](https://docs.qgroundcontrol.com/en/SettingsView/General.html) > Miscellaneous > Stream GCS Position** is set to *Never*. +::: ## Create the Plugin -> **Tip** `FollowMe` objects are created in the same way as other SDK plugins. - General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: tip +`FollowMe` objects are created in the same way as other SDK plugins. +General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: The main steps are: @@ -76,7 +80,9 @@ Use [set_target_location()](../api_reference/classmavsdk_1_1_follow_me.md#classm This can be called at any time, but messages will only be sent once following is started. The plugin automatically resends the last set position at the rate required by the autopilot/flight mode (1 Hz). -> **Note** Typically you would call `set_target_location()` before or shortly after starting the mode. If you call `start()` without having set any target location, or if the connection is broken, the vehicle will climb to minimum altitude (if needed) and remain in the mode waiting for messages. +::: info +Typically you would call `set_target_location()` before or shortly after starting the mode. If you call `start()` without having set any target location, or if the connection is broken, the vehicle will climb to minimum altitude (if needed) and remain in the mode waiting for messages. +::: ```cpp // Start following diff --git a/docs/en/cpp/guide/general_usage.md b/docs/en/cpp/guide/general_usage.md index e9d9a9ddb..6809ac720 100644 --- a/docs/en/cpp/guide/general_usage.md +++ b/docs/en/cpp/guide/general_usage.md @@ -21,8 +21,10 @@ All objects are automatically cleaned up when the parent `Mavsdk` object is dest MAVSDK APIs do not raise exceptions! Instead, methods that can fail return success or an error reason as `enum` values. -> **Tip** The error code usually reflects acknowledgment from the vehicle that it will perform the requested action (or not). - The operation itself may not yet have completed (e.g. taking off). +::: tip +The error code usually reflects acknowledgment from the vehicle that it will perform the requested action (or not). +The operation itself may not yet have completed (e.g. taking off). +::: The various classes also all provide stream operators for getting human readable strings from their associated result enum. You can see how these are used in the example code. diff --git a/docs/en/cpp/guide/installation.md b/docs/en/cpp/guide/installation.md index a51411996..e03a0f8b0 100644 --- a/docs/en/cpp/guide/installation.md +++ b/docs/en/cpp/guide/installation.md @@ -32,5 +32,7 @@ brew install mavsdk For Windows you can download the **mavsdk-windows-x64-release.zip** file from [MAVSDK releases](https://github.com/mavlink/MAVSDK/releases) containing the headers and library and extract it locally (see [information how to use a locally installed library](toolchain.md#sdk_local_install)). -> **Note** As the library is installed locally (in a local directory) you need to point cmake to that directory at configure time using `CMAKE_PREFIX_PATH` when building your application. -> i.e.: `cmake -Bbuild -DCMAKE_PREFIX_PATH=../mavsdk_extracted` -H. +::: info +As the library is installed locally (in a local directory) you need to point cmake to that directory at configure time using `CMAKE_PREFIX_PATH` when building your application. +i.e.: `cmake -Bbuild -DCMAKE_PREFIX_PATH=../mavsdk_extracted` -H. +::: diff --git a/docs/en/cpp/guide/missions.md b/docs/en/cpp/guide/missions.md index d471b7734..ee174a037 100644 --- a/docs/en/cpp/guide/missions.md +++ b/docs/en/cpp/guide/missions.md @@ -6,8 +6,10 @@ Missions can have multiple "mission items", each which may specify a position, a Missions are *managed* though the [Mission](../api_reference/classmavsdk_1_1_mission.md) class, which communicates with the vehicle to upload mission information and run, pause, track the mission progress etc. The mission that is uploaded to the vehicle is defined as a vector of [MissionItem](../api_reference/structmavsdk_1_1_mission_1_1_mission_item.md) objects. -> **Tip** The [Mission plugin](../api_reference/classmavsdk_1_1_mission.md) described here only supports a small subset of the full functionality of MAVLink missions. If you require the full mission item spec as MAVLink provides it, you might be better off using the [MissionRaw plugin](../api_reference/classmavsdk_1_1_mission_raw.md). -> Furthermore MissionRaw allows importing mission from QGroundControl. +::: tip +The [Mission plugin](../api_reference/classmavsdk_1_1_mission.md) described here only supports a small subset of the full functionality of MAVLink missions. If you require the full mission item spec as MAVLink provides it, you might be better off using the [MissionRaw plugin](../api_reference/classmavsdk_1_1_mission_raw.md). +Furthermore `MissionRaw` allows importing mission from QGroundControl. +::: ## Supported Mission Commands {#supported_mission_commands} @@ -27,14 +29,18 @@ Additionally, the following commands are supported only for mission import/downl * [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) * [MAV_CMD_NAV_TAKEOFF](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_TAKEOFF) -> **Tip** The Mission API does not (at time of writing) provide explicit functionality to "repeat", takeoff, return to land etc. -> The SDK provides some omitted functionality through the [Action](../guide/taking_off_landing.md) API. +::: tip +The Mission API does not (at time of writing) provide explicit functionality to "repeat", takeoff, return to land etc. +The SDK provides some omitted functionality through the [Action](../guide/taking_off_landing.md) API. +::: ## Create the Plugin -> **Tip** `Mission` objects are created in the same way as other MAVSDK plugins. - General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: tip +`Mission` objects are created in the same way as other MAVSDK plugins. +General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: The main steps are: @@ -99,12 +105,15 @@ new_item2->camera_photo_interval_s = 1.0f; mission_items.push_back(new_item2); ``` -> **Note** The autopilot has sensible default values for the attributes. - If you do set a value (e.g. the desired speed) then it will be the default for the remainder of the mission. +::: info +The autopilot has sensible default values for the attributes. +If you do set a value (e.g. the desired speed) then it will be the default for the remainder of the mission. +::: - -> **Note** There are also getter methods for querying the current value of `MissionItem` attributes. - The default values of most fields are `NaN` (which means they are ignored/not sent). +::: info +There are also getter methods for querying the current value of `MissionItem` attributes. +The default values of most fields are `NaN` (which means they are ignored/not sent). +::: The mission (`mission_items`) can then be uploaded as shown in the section [Uploading a Mission](#uploading_mission) below. @@ -207,7 +216,9 @@ mission.subscribe_mission_progress( [](Mission::MissionProgress mission_progress }); ``` -> **Note** The mission is complete when `current == total`. +::: info +The mission is complete when `current == total`. +::: The following synchronous methods is also available for checking mission progress: * [is_mission_finished()](../api_reference/classmavsdk_1_1_mission.md#classmavsdk_1_1_mission_1a1ecf4f8798ab9ae96882dfbd34f23466) - Checks if mission has been finished. @@ -229,9 +240,11 @@ If required you can instead use the appropriate commands in the [Action](../guid Use [Mission::download_mission()](../api_reference/classmavsdk_1_1_mission.md#classmavsdk_1_1_mission_1a23e9f7da32f42bcce7ef16ea8044fe53) to download a mission from the vehicle. The mission is downloaded as a vector of [MissionItem](../api_reference/structmavsdk_1_1_mission_1_1_mission_item.md) objects, that you can then view or manipulate as required. -> **Note** Mission download will fail if the mission contains a command that is outside the [supported set](#supported_mission_commands). -> Missions created using *QGroundControl* are not guaranteed to successfully download! -> Again, for that case [MissionRaw](../api_reference/classmavsdk_1_1_mission_raw.md) might be a better fit. +::: info +Mission download will fail if the mission contains a command that is outside the [supported set](#supported_mission_commands). +Missions created using *QGroundControl* are not guaranteed to successfully download! +Again, for that case [MissionRaw](../api_reference/classmavsdk_1_1_mission_raw.md) might be a better fit. +::: The code fragment below shows how to download a mission: diff --git a/docs/en/cpp/guide/offboard.md b/docs/en/cpp/guide/offboard.md index f3dd0314d..592675e09 100644 --- a/docs/en/cpp/guide/offboard.md +++ b/docs/en/cpp/guide/offboard.md @@ -3,8 +3,10 @@ The [Offboard](../api_reference/classmavsdk_1_1_offboard.md) MAVSDK plugin provides a simple API for controlling the vehicle using velocity and yaw setpoints. It is useful for tasks requiring direct control from a companion computer; for example to implement collision avoidance. -> **Note** The API uses the PX4 [Offboard flight mode](https://docs.px4.io/master/en/flight_modes/offboard.html). - The class can only be used with copter and VTOL vehicles (not fixed wing - a PX4 limitation) and currently only supports *velocity setpoint commands* (PX4 additionally supports position and thrust setpoints). +::: info +The API uses the PX4 [Offboard flight mode](https://docs.px4.io/master/en/flight_modes/offboard.html). +The class can only be used with copter and VTOL vehicles (not fixed wing - a PX4 limitation) and currently only supports *velocity setpoint commands* (PX4 additionally supports position and thrust setpoints). +::: Client code must specify a setpoint before starting *Offboard mode*. The Offboard plugin automatically resends setpoints at 20Hz (PX4 requires that setpoints are minimally resent at 2Hz). @@ -13,8 +15,10 @@ If more precise control is required, clients can call the setpoint methods at wh ## Create the Plugin -> **Tip** `Offboard` objects are created in the same way as other SDK plugins. - General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: tip +`Offboard` objects are created in the same way as other SDK plugins. +General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: The main steps are: @@ -73,7 +77,9 @@ if (result != Offboard::Result::Success) { } ``` -> **Note** Offboard mode can also be stopped by moving the vehicle into another mode (e.g. using the `Action` API). +::: info +Offboard mode can also be stopped by moving the vehicle into another mode (e.g. using the `Action` API). +::: ## Velocity Setpoints diff --git a/docs/en/cpp/guide/system_information.md b/docs/en/cpp/guide/system_information.md index 0785fed82..46700a838 100644 --- a/docs/en/cpp/guide/system_information.md +++ b/docs/en/cpp/guide/system_information.md @@ -2,9 +2,10 @@ The [Info](../api_reference/classmavsdk_1_1_info.md) class is used to get system (vehicle) information, including the UUID (MAVLink `SYS_ID` if no UUID is stored in hardware), PX4 firmware version, vendor firmware version, host OS version (e.g. for NuttX) and vendor and product ids/names. -> **Note** Not all version information will necessarily be relevant on all vehicles. Where this occurs the -hardware may return garbage values (for example, the simulator provides garbage values for the vendor -firmware semantic version). +::: info +Not all version information will necessarily be relevant on all vehicles. +Where this occurs the hardware may return garbage values (for example, the simulator provides garbage values for the vendor firmware semantic version). +::: ## Preconditions @@ -23,7 +24,10 @@ auto info = Info{system}; The code below shows how to query the hardware uid, version, and product, information and print it to the console: -> **Tip** The UUID/uid with type uint64_t has been replaced by uid2 called hardware_uid with type char[18]. This was a a change inherited from mavlink in order to prevent ID conflicts. +::: tip +The UUID/uid with type uint64_t has been replaced by uid2 called hardware_uid with type char[18]. +This was a a change inherited from mavlink in order to prevent ID conflicts. +::: ```cpp std::cout << "hardware uid: " << info.hardware_uid() << '\n'; @@ -60,5 +64,7 @@ std::cout << " vendor_id: " << systemProduct.vendor_id<< '\n' << " product_name: " << systemProduct.product_id<< '\n'; ``` -> **Tip** It is possible to query for the information before all values have been retrieved. - Note above how we use `Info::is_complete()` to check that the version information (`Info::Version` and `Info::Product`) has all been obtained from the vehicle before printing it. +::: tip +It is possible to query for the information before all values have been retrieved. +Note above how we use `Info::is_complete()` to check that the version information (`Info::Version` and `Info::Product`) has all been obtained from the vehicle before printing it. +::: diff --git a/docs/en/cpp/guide/taking_off_landing.md b/docs/en/cpp/guide/taking_off_landing.md index 129cbca7f..fddaf9067 100644 --- a/docs/en/cpp/guide/taking_off_landing.md +++ b/docs/en/cpp/guide/taking_off_landing.md @@ -6,13 +6,17 @@ Most of the methods have both synchronous and asynchronous versions. The methods send commands to a vehicle, and return/complete with the vehicle's response. It is important to understand that a successful response indicates whether or not the vehicle intends to act on the command, not that it has finished the action (e.g. arming, landing, taking off etc.). -> **Note** The implication is that you may need to monitor for completion of actions! +::: info +The implication is that you may need to monitor for completion of actions! +::: ## Create the Plugin -> **Tip** `Action` objects are created in the same way as for other SDK plugins. +::: tip +`Action` objects are created in the same way as for other SDK plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: The main steps are: @@ -36,16 +40,20 @@ The main steps are: The `action` object can then used to access the plugin API (as shown in the following sections). -> **Note** Some of the sections below additionally assume you have created a `Telemetry` instance that can be accessed using `telemetry`. +::: info +Some of the sections below additionally assume you have created a `Telemetry` instance that can be accessed using `telemetry`. +::: ## Taking Off The recommended way to take off using the SDK (and PX4) is to use either of the [takeoff()](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1a0121d39baf922b1d88283230207ab5d0) or [takeoff_async()](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1ab658d938970326db41709d83e02b41e6) methods. If a takeoff command is accepted the vehicle will change to the [Takeoff mode](https://docs.px4.io/master/en/flight_modes/takeoff.html), fly to the takeoff altitude, and then hover (in takeoff mode) until another instruction is received. -> **Note** PX4/SDK also provides other ways to take off: -> - A copter or VTOL will take off automatically if a mission is started (fixed-wing will not). -> - You can also take off by manually driving the vehicle using the offboard API. +::: info +PX4/SDK also provides other ways to take off: +- A copter or VTOL will take off automatically if a mission is started (fixed-wing will not). +- You can also take off by manually driving the vehicle using the offboard API. +::: The vehicle will only take off once *armed*, and can only arm once it is "healthy" (has been calibrated, the home position has been set, and there is a high-enough quality GPS lock). After it starts flying, code needs to check that takeoff is complete before sending additional instructions. @@ -106,7 +114,9 @@ while (telemetry.health_all_ok() != true) { } ``` -> **Note** Vehicle health can also be checked using [Telemetry:subscribe_health_all_ok()](../api_reference/classmavsdk_1_1_telemetry.md#classmavsdk_1_1_telemetry_1a0f94ea6d707ff314e412367d6681bd8f). +::: info +Vehicle health can also be checked using [Telemetry:subscribe_health_all_ok()](../api_reference/classmavsdk_1_1_telemetry.md#classmavsdk_1_1_telemetry_1a0f94ea6d707ff314e412367d6681bd8f). +::: ### Arming @@ -123,7 +133,9 @@ if (arm_result != Action::Result::Success) { } ``` -> **Tip** If the `arm()` method returns `Action::Result::Success` then the vehicle is armed and can proceed to takeoff. This can be confirmed using [Telemetry::armed()](../api_reference/classmavsdk_1_1_telemetry.md#classmavsdk_1_1_telemetry_1a6620142adc47f069262e5bf69dbb3876). +::: tip +If the `arm()` method returns `Action::Result::Success` then the vehicle is armed and can proceed to takeoff. This can be confirmed using [Telemetry::armed()](../api_reference/classmavsdk_1_1_telemetry.md#classmavsdk_1_1_telemetry_1a6620142adc47f069262e5bf69dbb3876). +::: ### Get/Set Takeoff Altitude @@ -151,7 +163,9 @@ if (takeoff_result != Action::Result::Success) { If the command succeeds the vehicle will takeoff, and hover at the takeoff altitude. Code should wait until takeoff has completed before sending the next instruction. Unfortunately there is no specific indicator to inform code that takeoff is complete. -> **Note** One alternative is to simply wait for enough time that the vehicle *should* have reached the takeoff altitude. +::: info +One alternative is to simply wait for enough time that the vehicle *should* have reached the takeoff altitude. +::: The code below checks for takeoff completion by polling the current altitude until the target altitude is reached: @@ -171,7 +185,9 @@ while (current_position **Note** The SDK does not at time of writing recommend other approaches for landing: land mission items are not supported and manually landing the vehicle using the offboard is not as safe. +::: info +The SDK does not at time of writing recommend other approaches for landing: land mission items are not supported and manually landing the vehicle using the offboard is not as safe. +::: The code below shows how to use the land action. @@ -220,7 +236,9 @@ The methods are listed below. These are used in the same way as other similar `A - [kill()](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1af40fc1ddf588b3796134a9303ebc3667), [kill_async](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1a78c1f15c3b190ba94793045621819e69) -> **Tip** PX4 will automatically disarm the vehicle after landing. The disarm methods explicitly invoke the same functionality. +::: tip +PX4 will automatically disarm the vehicle after landing. The disarm methods explicitly invoke the same functionality. +::: ## Get/Set Cruise Speed @@ -229,8 +247,10 @@ You can get/set the normal horizontal velocity used in *Return mode*, *Hold mode * [set_maximum_speed()](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1a5fccee1636215bccf8d77d9dca15134e) * [get_maximum_speed](../api_reference/classmavsdk_1_1_action.md#classmavsdk_1_1_action_1a128bf73fe8d0d359f36a3a9a327799ee) -> **Note** These methods get/set the [MPC_XY_CRUISE](https://docs.px4.io/master/en/advanced_config/parameter_reference.html#MPC_XY_CRUISE) parameter. - They are used in the same way as the other `Action` methods. +::: info +These methods get/set the [MPC_XY_CRUISE](https://docs.px4.io/master/en/advanced_config/parameter_reference.html#MPC_XY_CRUISE) parameter. +They are used in the same way as the other `Action` methods. +::: diff --git a/docs/en/cpp/guide/telemetry.md b/docs/en/cpp/guide/telemetry.md index f66bf249e..9a455ea5e 100644 --- a/docs/en/cpp/guide/telemetry.md +++ b/docs/en/cpp/guide/telemetry.md @@ -46,8 +46,10 @@ In addition there are a number of methods that return vehicle "state": ## Create the Plugin -> **Tip** `Telemetry` objects are created in the same way as objects in other SDK plugins. +::: tip +`Telemetry` objects are created in the same way as objects in other SDK plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). +::: The main steps are: @@ -77,8 +79,10 @@ The `telemetry` object can then used to access the plugin API (as shown in the f The telemetry update rate determines the frequency at which callbacks will be invoked with new information, and also the probable "freshness" of data obtained when using synchronous telemetry APIs. The default update rate depends on the autopilot and may also be limited by the characteristics of the communications channel. You can set the rate for *each* type of telemetry, and both synchronous or asynchronous rate-setting methods are provided. -> **Note** For PX4 running on hardware the *default* rates are set on a per-mode basis in [mavlink_main.cpp](https://github.com/PX4/Firmware/blob/master/src/modules/mavlink/mavlink_main.cpp#L2025) (search on `configure_stream`). - For PX4 running on SITL, the default rates are defined in the [startup file](https://docs.px4.io/master/en/concept/system_startup.html). +::: info +For PX4 running on hardware the *default* rates are set on a per-mode basis in [mavlink_main.cpp](https://github.com/PX4/Firmware/blob/master/src/modules/mavlink/mavlink_main.cpp#L2025) (search on `configure_stream`). +For PX4 running on SITL, the default rates are defined in the [startup file](https://docs.px4.io/master/en/concept/system_startup.html). +::: The rate-setting methods are all used in the same way, so we just show one example for both the asynchronous and synchronous methods below. In both cases we set the rate for position updates. @@ -166,7 +170,9 @@ telemetry.subscribe_flight_mode(nullptr); This same approach can be used to report only messages that meet some condition. -> **Tip** In future we may add a mechanism *in the API* to support just reporting changes: [Issue #63](https://github.com/mavlink/MAVSDK/issues/63). +::: tip +In future we may add a mechanism *in the API* to support just reporting changes: [Issue #63](https://github.com/mavlink/MAVSDK/issues/63). +::: ## Blocking Telemetry Requests (State Management) @@ -206,8 +212,10 @@ Similarly, you can use the asynchronous method and block // Now ready to arm } ``` -> **Note** Note that `prom->set_value()` must only be called once. - If your code can potentially call this multiple times, remember to unsubscribe from the callback after it succeeds (e.g. using `telemetry.subscribe_health_all_ok(nullptr)`). +::: info +Note that `prom->set_value()` must only be called once. +If your code can potentially call this multiple times, remember to unsubscribe from the callback after it succeeds (e.g. using `telemetry.subscribe_health_all_ok(nullptr)`). +::: Depending on the architecture of your application, you may even wish to arm the vehicle in your callback function. Usually though it is easier to understand program flow using the approach above. diff --git a/docs/en/cpp/guide/test.md b/docs/en/cpp/guide/test.md index dcbf096d2..22780c1fd 100644 --- a/docs/en/cpp/guide/test.md +++ b/docs/en/cpp/guide/test.md @@ -5,7 +5,9 @@ The unit tests are run every time new code is committed to the library, and must This topic shows how to run the existing tests. -> **Tip** For information on _writing_ tests see: [Writing Plugins > Test Code](../contributing/plugins.md#testing). +::: tip +For information on _writing_ tests see: [Writing Plugins > Test Code](../contributing/plugins.md#testing). +::: ## Running Unit Tests @@ -19,10 +21,11 @@ To run all unit tests: Tests can be run against the simulator (either manually starting PX4 SITL or letting the tests start it automatically) or against a real vehicle. -> **Tip** To run SITL you will need to install the _Gazebo_ simulator. -> This is included as part of the standard PX4 installation for [macOS](https://docs.px4.io/master/en/dev_setup/dev_env_mac.html) -> and [Linux](https://docs.px4.io/master/en/dev_setup/dev_env_linux_ubuntu.html). -> It does not run on Windows. +::: tip +To run SITL you will need to install the _Gazebo_ simulator. +This is included as part of the standard PX4 installation for [macOS](https://docs.px4.io/master/en/dev_setup/dev_env_mac.html) and [Linux](https://docs.px4.io/master/en/dev_setup/dev_env_linux_ubuntu.html). +It does not run on Windows. +::: ### Autostart PX4 SITL @@ -62,7 +65,9 @@ cd path/to/MAVSDK/ ./build/debug/src/integration_tests/integration_tests_runner ``` -> **Tip** The tests are designed to run in simulation, and may not be safe if run on a real vehicle. +::: tip +The tests are designed to run in simulation, and may not be safe if run on a real vehicle. +::: ### Gtest Tricks diff --git a/docs/en/cpp/guide/toolchain.md b/docs/en/cpp/guide/toolchain.md index 3d6468c1e..03f1a13a5 100644 --- a/docs/en/cpp/guide/toolchain.md +++ b/docs/en/cpp/guide/toolchain.md @@ -16,7 +16,9 @@ Below we explain how to set up a minimal build setup (**CMakeLists.txt**) file f The sections below show how you can set up the file for when the SDK is [installed system wide](installation.md) (the default) or [locally](build.md#sdk_local_install). -> **Warning** On Windows use the [local installation](#sdk_local_install). +::: warning +On Windows use the [local installation](#sdk_local_install). +::: A "template" **CMakeLists.txt** is shown below. Most of file is boilerplate - the main things you need to change are *your_project_name*, *your_executable_name* and *your_source_file*. You should also make sure that any plugins used by your app are listed in the `target_link_libraries` section. @@ -52,8 +54,10 @@ target_link_libraries(your_executable_name ) ``` -> **Note** The file format and required modifications are self-explanatory. -> If additional information is required see the [cmake documentation](https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html). +::: info +The file format and required modifications are self-explanatory. +If additional information is required see the [cmake documentation](https://cmake.org/cmake/help/latest/manual/cmake-commands.7.html). +::: ## Building the App diff --git a/docs/en/cpp/guide/using_plugins.md b/docs/en/cpp/guide/using_plugins.md index 7187d9774..dced933eb 100644 --- a/docs/en/cpp/guide/using_plugins.md +++ b/docs/en/cpp/guide/using_plugins.md @@ -5,10 +5,14 @@ For example, the [Action](../api_reference/classmavsdk_1_1_action.md) plugin is while the [Telemetry](../guide/telemetry.md) plugin can be used to query the vehicle GPS status, flight mode, etc. A separate plugin instance must be created for each system that needs it. -> **Note** All plugins are declared/used in the same way. This topic uses the `Action` plugin for the purposes of the demonstration. +::: info +All plugins are declared/used in the same way. This topic uses the `Action` plugin for the purposes of the demonstration. +::: -> **Note** Plugins are named using the convention **mavsdk\__plugin\_name_.so**. - For more information see [Building C++ Apps](../guide/toolchain.md) +::: info +Plugins are named using the convention **mavsdk\__plugin\_name_.so**. +For more information see [Building C++ Apps](../guide/toolchain.md) +::: In the application source code: diff --git a/docs/en/cpp/guide/vtol.md b/docs/en/cpp/guide/vtol.md index 1a9ed1720..a813056bb 100644 --- a/docs/en/cpp/guide/vtol.md +++ b/docs/en/cpp/guide/vtol.md @@ -3,8 +3,10 @@ MAVSDK has only basic support for VTOL vehicles. VTOL waypoint missions are only supported using the [MissionRaw plugin](../api_reference/classmavsdk_1_1_mission_raw.md). -> **Note** Most design and test effort has gone into multicopter support. -> [Get in touch](../../index.md#getting-help) if you would like to help enhance the VTOL/Fixed-wing experience! +::: info +Most design and test effort has gone into multicopter support. +[Get in touch](../../index.md#getting-help) if you would like to help enhance the VTOL/Fixed-wing experience! +::: ## Supported Functionality diff --git a/docs/en/cpp/quickstart.md b/docs/en/cpp/quickstart.md index 8eb61a278..c4f25fcae 100644 --- a/docs/en/cpp/quickstart.md +++ b/docs/en/cpp/quickstart.md @@ -2,7 +2,9 @@ This quickstart shows you how to build and run a simple MAVSDK C++ example application against a simulated vehicle, and observe the operation using the console and in a ground station. -> **Note** MAVSDK is essentially a C++ library (or rather multiple library files) that you can include and link in your C++ application. +::: info +MAVSDK is essentially a C++ library (or rather multiple library files) that you can include and link in your C++ application. +::: ## Install MAVSDK library @@ -89,8 +91,10 @@ build/takeoff_and_land udp://:14540 The MAVSDK application should connect to PX4, and you will be able to observe the example running in the SDK terminal, SITL terminal, and/or *QGroundControl*. The expected behaviour is shown here: [Example: Takeoff and Land](examples/takeoff_and_land.md). -> **Note** The first argument above is the connection string (`udp://:14540`). - This is the standard PX4 UDP port for connecting to offboard APIs (also see [Connecting to Systems](guide/connections.md)). +::: info +The first argument above is the connection string (`udp://:14540`). +This is the standard PX4 UDP port for connecting to offboard APIs (also see [Connecting to Systems](guide/connections.md)). +::: ## Next Steps diff --git a/docs/en/cpp/server_plugins.md b/docs/en/cpp/server_plugins.md index f1fb29537..7a145c32c 100644 --- a/docs/en/cpp/server_plugins.md +++ b/docs/en/cpp/server_plugins.md @@ -4,8 +4,10 @@ MAVSDK _Server_ plugins are used to expose MAVLink services on non-MAVLink fligh The plugins listen for commands from a ground station or other MAVLink client, pass them to the underlying native system using callbacks, and respond as needed. -> **Note** They are called "server" plugins because they perform the server role in communication - listening for commands and responding. -> The client role is usually performed by a ground station (or "ordinary" MAVSDK plugin) +::: info +They are called "server" plugins because they perform the server role in communication - listening for commands and responding. +The client role is usually performed by a ground station (or "ordinary" MAVSDK plugin) +::: ## Adding MAVLink support to your vehicle diff --git a/docs/en/faq.md b/docs/en/faq.md index e9ecaee2b..e7f4018a6 100644 --- a/docs/en/faq.md +++ b/docs/en/faq.md @@ -15,10 +15,12 @@ Yes. A maximum of 255 vehicles can be connected. -> **Note** The maximum number of vehicles is defined by the MAVLink protocol. - MAVLink refers to vehicles as "systems", which are comprised of components (for example, a drone with a gimbal and a camera). - Each system has a network-unique MAVLink system ID, with a value between 1 and 255 (0 is a "broadcast address"). - Each component in a system shares its system id, and has a system-unique component ID, again with a value 1 and 255. +::: info +The maximum number of vehicles is defined by the MAVLink protocol. +MAVLink refers to vehicles as "systems", which are comprised of components (for example, a drone with a gimbal and a camera). +Each system has a network-unique MAVLink system ID, with a value between 1 and 255 (0 is a "broadcast address"). +Each component in a system shares its system id, and has a system-unique component ID, again with a value 1 and 255. +::: ### Is MAVLink 1 supported? @@ -45,8 +47,10 @@ MAVSDK, so far, is optimised for use with the PX4 flight stack and all testing i While many features should work on other flight stacks there may be implementation differences at the [MAVLink microservices level](https://mavlink.io/en/protocol/overview.html) which means that not every API will work. For example, PX4 and ArduPilot implement the parameter protocol differently, and vary slightly in the mission upload/download protocol (e.g. ArduPilot uses the 0 entry as the home position). -> **Note** The SDK welcomes contributions to better support flight stacks other than PX4. -> We do however expect contributors to also help with testing and maintenance support for using the SDK with their autopilot. +::: info +The SDK welcomes contributions to better support flight stacks other than PX4. +We do however expect contributors to also help with testing and maintenance support for using the SDK with their autopilot. +::: ### Are serial connections supported? diff --git a/docs/en/python/quickstart.md b/docs/en/python/quickstart.md index 87e44e2c0..936d5943b 100644 --- a/docs/en/python/quickstart.md +++ b/docs/en/python/quickstart.md @@ -16,7 +16,9 @@ pip3 install mavsdk Make sure that the output of this command confirms that the installation succeeded! -> **Tip** On some systems, you may have to run `pip3 install --user mavsdk`, or you may want to run in a Python venv. +::: tip +On some systems, you may have to run `pip3 install --user mavsdk`, or you may want to run in a Python venv. +::: For the quick start below we will also install the lightweight package called “aioconsole”. This provides a REPL (interactive shell) called `apython` that we can use for running asyncio code: @@ -75,7 +77,9 @@ Here is what it looks like in jMAVSim: ![jMAVSim after a successful takeoff](../../assets/python/quickstart/jmavsim_takeoff.png) -> **Note** Make sure to send the `takeoff()` command within (at most) a few seconds of `arm()`; the drone will automatically disarm after a few seconds if it does not receive a command to takeoff. +::: info +Make sure to send the `takeoff()` command within (at most) a few seconds of `arm()`; the drone will automatically disarm after a few seconds if it does not receive a command to takeoff. +::: You get an exception, as shown below: ```python @@ -93,7 +97,9 @@ Now that the drone is flying, we can land: await drone.action.land() ``` -> **Note** We have been using the apython REPL to run all that interactively, but the same can be achieved by running the [takeoff_and_land.py](https://github.com/mavlink/MAVSDK-Python/blob/master/examples/takeoff_and_land.py) example (in which case the `aioconsole` package is not needed). +::: info +We have been using the apython REPL to run all that interactively, but the same can be achieved by running the [takeoff_and_land.py](https://github.com/mavlink/MAVSDK-Python/blob/master/examples/takeoff_and_land.py) example (in which case the `aioconsole` package is not needed). +::: ## Using an IDE