Add MavlinkDirect docs and more examples

README.md

@@ -13,7 +13,7 @@ It aims to be:
 - Easy to use with a simple API supporting both synchronous (blocking) API calls and asynchronous API calls using callbacks.
 - Fast and lightweight.
 - Cross-platform (Linux, macOS, Windows, iOS, Android).
-- Extensible (using the MavlinkPassthrough plugin).
+- Extensible (using the `MavlinkDirect` plugin, or the soon-to-be-deprecated `MavlinkPassthrough` plugin).
 - Fully compliant with the MAVLink standard/definitions.
 
 In order to support multiple programming languages, MAVSDK implements a gRPC server in C++ which allows clients in different programming languages to connect to. The API is defined by the proto IDL ([proto files](https://github.com/mavlink/MAVSDK-Proto/tree/master/protos)).

docs/.vitepress/config.mjs

@@ -144,7 +144,7 @@ export default defineConfig({
         text: "Version",
         items: [
           {
-            text: "main",
+            text: "main / v3",
             link: "https://mavsdk.mavlink.io/main/en/cpp/api_changes.html",
           },
           {

docs/en/SUMMARY.md

@@ -15,6 +15,7 @@
         * [Offboard Control](cpp/guide/offboard.md)
         * [Follow Me](cpp/guide/follow_me.md)
         * [VTOL Support](cpp/guide/vtol.md)
+        * [MavlinkDirect](cpp/guide/mavlink_direct.md)
         * [Building C++ Apps](cpp/guide/toolchain.md)
         * [Logging](cpp/guide/logging.md)
         * [Plugin/Test Logging](cpp/guide/dev_logging.md)
@@ -116,6 +117,8 @@
         * [class LogStreaming](cpp/api_reference/classmavsdk_1_1_log_streaming.md)
             * [struct LogStreamingRaw](cpp/api_reference/structmavsdk_1_1_log_streaming_1_1_log_streaming_raw.md)
         * [class ManualControl](cpp/api_reference/classmavsdk_1_1_manual_control.md)
+        * [class MavlinkDirect](cpp/api_reference/classmavsdk_1_1_mavlink_direct.md)
+            * [struct MavlinkMessage](cpp/api_reference/structmavsdk_1_1_mavlink_direct_1_1_mavlink_message.md)
         * [class MavlinkPassthrough](cpp/api_reference/classmavsdk_1_1_mavlink_passthrough.md)
             * [struct CommandInt](cpp/api_reference/structmavsdk_1_1_mavlink_passthrough_1_1_command_int.md)
             * [struct CommandLong](cpp/api_reference/structmavsdk_1_1_mavlink_passthrough_1_1_command_long.md)

docs/en/cpp/api_reference/classmavsdk_1_1_mavlink_passthrough.md

@@ -7,7 +7,20 @@
 The [MavlinkPassthrough](classmavsdk_1_1_mavlink_passthrough.md) class provides direct MAVLink access. 
 
 
-"With great power comes great responsibility." - This plugin allows you to send and receive MAVLink messages. There is no checking or safe-guards, you're on your own, and you have been warned. 
+"With great power comes great responsibility." - This plugin allows you to send and receive MAVLink messages. There is no checking or safe-guards, you're on your own, and you have been warned.
+
+
+::: warning
+[MavlinkPassthrough](classmavsdk_1_1_mavlink_passthrough.md) will get deprecated in MAVSDK v4 and will only be available built from source. Use [MavlinkDirect](classmavsdk_1_1_mavlink_direct.md) instead. [MavlinkDirect](classmavsdk_1_1_mavlink_direct.md) provides enhanced functionality including:
+<ul>
+<li><p>Runtime message parsing with JSON field representation</p>
+</li>
+<li><p>Custom message support via XML loading</p>
+</li>
+<li><p>Better language wrapper integration </p>
+</li>
+</ul>
+:::
 
 
 ## Data Structures

docs/en/cpp/guide/mavlink_direct.md

@@ -0,0 +1,227 @@
+# MavlinkDirect
+
+The [MavlinkDirect](../cpp/api_reference/classmavsdk_1_1_mavlink_direct.md) plugin enables direct MAVLink communication with runtime message parsing and JSON field representation.
+
+::: warning
+The MavlinkDirect API is quite new and is not necessarily stabilized yet.
+The functionality is here to stay but the specifics and types might still change before MAVSDK v4.
+:::
+
+::: tip
+MavlinkDirect is the recommended replacement for [MavlinkPassthrough](../cpp/api_reference/classmavsdk_1_1_mavlink_passthrough.md).
+In MAVSDK v4, MavlinkPassthrough will only be available as a compile-time option.
+:::
+
+::: info
+The MavlinkDirect plugin is built on top of the work by Thomas Debrunner in [libmav](https://github.com/Auterion/libmav).
+:::
+
+## Overview
+
+MavlinkDirect allows you to:
+
+- Send and receive any MAVLink message
+- Load custom MAVLink message definitions from XML
+
+## Runtime vs compile-time considerations
+
+MavlinkDirect works at runtime instead of compile-time, so instead of having the C types and functions to rely on, everything has to be done using string methods. There are trade-offs with that:
+
+**Runtime pros:**
+
+- Allows extension with custom messages/dialects without re-compiling MAVSDK.
+- Allows usage in language wrappers such as Python.
+- MAVSDK no longer needs to carry and install the MAVLink C headers.
+
+**Runtime cons:**
+
+- API users need to look up MAVLink message definitions and don't get auto-complete.
+- Enum values or flags/bits need to be assembled manually.
+- The API is likely slower although that's likely negligible in C++ as long as messages are not sent/received at very high rates (benchmarks outstanding).
+
+## Load custom MAVLink XML/ MAVLink dialects
+
+By default all messsages from the [common.xml](https://mavlink.io/en/messages/common.html) MAVLink dialect are available, loaded in.
+
+MavlinkDirect allows to load your own/custom MAVLink messages or other dialects.
+
+In the example below we load in the AIRSPEED message as it is drafted in development.xml but not yet moved to common.xml, and hence not available by default in MAVSDK yet:
+
+```cpp
+    std::string custom_xml = R"(
+<mavlink>
+    <messages>
+        <message id="295" name="AIRSPEED">
+            <description>Airspeed sensor data</description>
+            <field type="uint8_t" name="id">Sensor ID</field>
+            <field type="float" name="airspeed">Calibrated airspeed in m/s</field>
+            <field type="int16_t" name="temperature">Temperature in centidegrees</field>
+            <field type="float" name="raw_press">Raw differential pressure</field>
+            <field type="uint8_t" name="flags">Airspeed sensor flags</field>
+        </message>
+    </messages>
+</mavlink>)";
+
+    // Load custom XML
+    auto xml_result = mavlink_direct.load_custom_xml(custom_xml);
+    if (xml_result != MavlinkDirect::Result::Success) {
+        std::cerr << "Failed to load custom XML: " << xml_result << std::endl;
+        return 1;
+    }
+```
+
+Check out the [full example on GitHub](https://github.com/mavlink/MAVSDK/tree/main/examples/mavlink_direct_sender_custom)
+
+
+## Sending messages
+
+Let's assume we are a companion computer that detects obstacles and therefore needs to send the message [OBSTACLE_DISTANCE](https://mavlink.io/en/messages/common.html#OBSTACLE_DISTANCE) to the autopilot.
+
+```cpp
+// Set up as companion computer
+auto config = Mavsdk::Configuration{ComponentType::CompanionComputer};
+
+// Connect ...
+
+// Create MavlinkDirect plugin instance
+auto mavlink_direct = MavlinkDirect{system.value()};
+
+// Create a HEARTBEAT message
+MavlinkDirect::MavlinkMessage obstacle_distance{};
+obstacle_distance.message_name = "OBSTACLE_DISTANCE";
+obstacle_distance.system_id = config.get_system_id(); // Your component's system ID
+obstacle_distance.component_id = config.get_component_id(); // Your component's component ID
+obstacle_distance.target_system_id = 0; // Does not apply for this message
+obstacle_distance.target_component_id = 0; // Does not apply for this message
+
+// For now we just hard-code values for demonstration purposes.
+// We assume the sensor has is looking forward and has 8 segments with 10 degrees per segment,
+// so 80 degrees field of view.
+// On 3 segments we see an obstacle, the closest is at 7m.
+//
+// In a real application this JSON message content would of course be
+// assembled manually, or using a json library like jsoncpp or nlohmann/json.
+obstacle_distance.fields_json = R"({
+    "time_usec": 12345678,
+    "sensor_type": 3,
+    "distances": [
+        2000,   2000,  2000,  1000,   800,   700,  2000,  2000,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536,
+        65536, 65536, 65536, 65536, 65536, 65536, 65536, 65536
+    ],
+    "increment": 0,
+    "min_distance": 000,
+    "max_distance": 2000,
+    "increment_f": 10.0,
+    "angle_offset": -40.0,
+    "frame": 12
+})";
+
+while (true) {
+    // Send the message
+    auto result = mavlink_direct.send_message(obstacle_distance);
+    if (result == MavlinkDirect::Result::Success) {
+        std::cout << "OBSTACLE_DISTANCE message sent successfully" << std::endl;
+    } else {
+        std::cerr << "OBSTACLE_DISTANCE message could not be sent: " << result << std::endl;
+    }
+
+    std::this_thread::sleep_for(std::chrono::milliseconds(500));
+}
+```
+
+Check the full example on [GitHub](https://github.com/mavlink/MAVSDK/tree/main/examples/mavlink_direct_sender).
+
+## Receiving messages
+
+You can subscribe to specific message types:
+
+```cpp
+// Subscribe to GLOBAL_POSITION_INT messages
+auto handle = mavlink_direct.subscribe_message(
+    "GLOBAL_POSITION_INT",
+    [](MavlinkDirect::MavlinkMessage message) {
+        std::cout << "Received position: " << message.fields_json << std::endl;
+
+        // And this could now be parsed by jsoncpp or nlohmann/json:
+        // Json::Value json;
+        // Json::Reader reader;
+        // if (reader.parse(message.fields_json, json)) {
+        //     auto lat = json["lat"].asInt() / 1e7;  // Convert from degrees * 1e7
+        //     auto lon = json["lon"].asInt() / 1e7;
+        //     std::cout << "Position: " << lat << ", " << lon << std::endl;
+        // }
+    }
+);
+```
+
+Or all messages using the empty string `""`:
+
+```cpp
+// Subscribe to all incoming messages
+auto handle = mavlink_direct.subscribe_message(
+    "",  // Empty string = all messages
+    [](MavlinkDirect::MavlinkMessage message) {
+        std::cout << "Received " << message.message_name
+                  << " from system " << message.system_id
+                  << " component " << message.component_id << std::endl;
+    }
+);
+```
+
+And to unsubscribe again, just use the handle from the subscription, as usual.
+
+```cpp
+// Clean up subscription
+mavlink_direct.unsubscribe_message(handle);
+```
+
+## Sniffing all messages
+
+There is also [an example that demonstrates a generic MAVLink message sniffer](https://github.com/mavlink/MAVSDK/tree/main/examples/sniffer).
+
+::: info
+: This example uses the mavsdk.h intercept API rather than the MavlinkDirect plugin API, however, they are very similar.
+:::
+
+## JSON field format
+
+MavlinkDirect represents MAVLink message fields as JSON objects:
+
+```json
+{
+  "time_boot_ms": 12345,
+  "lat": 473977418,
+  "lon": -1223974560,
+  "alt": 100500,
+  "relative_alt": 50250,
+  "vx": 100,
+  "vy": -50,
+  "vz": 25,
+  "hdg": 18000
+}
+```
+
+**Key points:**
+
+- All field names match the MAVLink message definition
+- Numeric values preserve original MAVLink types and scaling
+- Arrays are represented as JSON arrays: `[1, 2, 3, 0, 0]`
+- NaN and infinity values are represented as `null`
+- Extended fields are automatically included
+
+## API reference
+
+See [API Reference](../api_reference/classmavsdk_1_1_mavlink_direct.md) for full details.
+
+## Troubleshooting
+
+### Can I get more debug information?
+
+Yes, set the environment variable `MAVSDK_MAVLINK_DIRECT_DEBUGGING=1` before running your binary.

docs/en/cpp/index.md

@@ -53,7 +53,8 @@ The following APIs provide more direct access to underlying MAVLink messages/typ
 They should only be used where features are missing from the main APIs above.
 * [Param](api_reference/classmavsdk_1_1_param.md): Raw access to get and set parameters.
 * [MissionRaw](api_reference/classmavsdk_1_1_mission_raw.md): Direct access to MAVLink mission items.
-* [MavlinkPassthrough](api_reference/classmavsdk_1_1_mavlink_passthrough.md): Provides full/direct MAVLink access
+* [MavlinkDirect](api_reference/classmavsdk_1_1_mavlink_direct.md): Modern MAVLink access with JSON field representation and runtime message parsing
+* [MavlinkPassthrough](api_reference/classmavsdk_1_1_mavlink_passthrough.md): **DEPRECATED** (use [MavlinkDirect](api_reference/classmavsdk_1_1_mavlink_direct.md) instead)
 
 
 ## Contributing/Extending

docs/en/index.md

@@ -1,9 +1,6 @@
 <div style="float:right; padding:10px; margin-right:20px;"><img src="../assets/site/sdk_logo_full.png" title="MAVSDK Logo" width="400px"/></div>
 
-# MAVSDK (main)
-
-[![Build and Test](https://github.com/mavlink/MAVSDK/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/mavlink/MAVSDK/actions/workflows/main.yml)
-[![Coverage Status](https://coveralls.io/repos/github/mavlink/MAVSDK/badge.svg?branch=main)](https://coveralls.io/github/mavlink/MAVSDK?branch=main)
+# MAVSDK (main / v3)
 
 *MAVSDK* is a collection of libraries for various programming languages to interface with [MAVLink](https://mavlink.io/en/) systems such as drones, cameras or ground systems.
 

examples/CMakeLists.txt

@@ -34,6 +34,8 @@ add_subdirectory(log_callback)
 add_subdirectory(logfile_download)
 add_subdirectory(log_streaming)
 add_subdirectory(mavlink_direct)
+add_subdirectory(mavlink_direct_sender)
+add_subdirectory(mavlink_direct_sender_custom)
 add_subdirectory(mavshell)
 add_subdirectory(multiple_drones)
 add_subdirectory(offboard)

examples/mavlink_direct/mavlink_stats.cpp

@@ -19,8 +19,8 @@ void usage(const std::string& bin_name)
               << "Connection URL format should be :\n"
               << " For TCP server: tcpin://<our_ip>:<port>\n"
               << " For TCP client: tcpout://<remote_ip>:<port>\n"
-              << " For UDP server: udp://<our_ip>:<port>\n"
-              << " For UDP client: udp://<remote_ip>:<port>\n"
+              << " For UDP server: udpin://<our_ip>:<port>\n"
+              << " For UDP client: udpout://<remote_ip>:<port>\n"
               << " For Serial : serial://</path/to/serial/dev>:<baudrate>]\n"
               << "For example, to connect to the simulator use URL: udpin://0.0.0.0:14540\n";
 }

examples/mavlink_direct/subscribe_gps.cpp

@@ -14,8 +14,8 @@ void usage(const std::string& bin_name)
               << "Connection URL format should be :\n"
               << " For TCP server: tcpin://<our_ip>:<port>\n"
               << " For TCP client: tcpout://<remote_ip>:<port>\n"
-              << " For UDP server: udp://<our_ip>:<port>\n"
-              << " For UDP client: udp://<remote_ip>:<port>\n"
+              << " For UDP server: udpin://<our_ip>:<port>\n"
+              << " For UDP client: udpout://<remote_ip>:<port>\n"
               << " For Serial : serial://</path/to/serial/dev>:<baudrate>]\n"
               << "For example, to connect to the simulator use URL: udpin://0.0.0.0:14540\n";
 }

examples/mavlink_direct_sender/CMakeLists.txt

@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.10.2)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+project(mavlink_direct_sender)
+
+find_package(MAVSDK REQUIRED)
+
+add_executable(sender
+    sender.cpp
+)
+
+target_link_libraries(sender
+    PRIVATE
+    MAVSDK::mavsdk
+)
+
+if(NOT MSVC)
+    target_compile_options(sender PRIVATE -Wall -Wextra)
+else()
+    target_compile_options(sender PRIVATE -W2)
+endif()
+