Docs v3 notes and pass

.github/workflows/main.yml

@@ -229,6 +229,22 @@ jobs:
       - name: check for diff
         run: git diff --exit-code
 
+  ubuntu24-docs-check:
+    name: ubuntu-24.04 (docs check)
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Install doxygen
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen
+      - name: generate docs
+        run: tools/generate_docs.sh --overwrite
+      - name: check for diff
+        run: git diff --exit-code
+
   deb-package:
     name: ${{ matrix.container_name }} (package, non-mavsdk_server)
     runs-on: ${{ matrix.container_name }}

docs/en/cpp/api_changes.md

@@ -4,6 +4,10 @@ This page tracks changes between versions.
 
 It covers both breaking (incompatible) and non-breaking changes.
 
+::: info
+All examples below are assuming `using namespace mavsdk`.
+:::
+
 ## Semantic Versioning
 
 MAVSDK follows [semver/Semantic Versioning](https://semver.org/) conventions where as possible.
@@ -21,6 +25,108 @@ This means that breaking changes to the API result in a bump of the major versio
 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.
 :::
 
+## v3
+
+### Connections
+
+In the past the connection syntax has caused quite a bit of confusion. Therefore, we decided to adapt the syntax for UDP and TCP connections slightly, mostly adopting the syntax that's already used in other software such as for instance pymavlink and mavlink-router.
+
+The change makes it explicit whether we are listening on a port (think server), or connecting to a port (think client).
+
+The new syntax for the 3 connection methods are described below:
+
+#### UDP connections
+
+```
+- UDP in  (server): udpin://our_ip:port
+- UDP out (client): udpout://remote_ip:port
+```
+
+For `udpin`, where we bind locally to that port, the IP can be set to:
+- `0.0.0.0` to listen on all network interfaces.
+- `127.0.0.1` to listen on the local loopback interface only.
+- to our IP which means we listen on this network interfaces only.
+
+#### TCP connections
+
+```
+- TCP in  (server):  tcpin://our_ip:port
+- TCP out (client): tcpout://remote_ip:port
+```
+
+For `tcpin`, where we listen locally on that port, the IP can be set to:
+- `0.0.0.0` to listen on all network interfaces.
+- `127.0.0.1` to listen on the local loopback interface only.
+- to our IP which means we listen on this network interfaces only.
+
+#### Serial connections
+
+```
+- Serial: serial://dev_node:baudrate
+- Serial with flow control: serial_flowcontrol://dev_node:baudrate
+```
+
+This is unchanged apart from the one caveat that the baudrate is no longer optional. This is to avoid cases where the baudrate is omitted by mistake.
+
+### Mavsdk configuration
+
+`ComponentType` is moved out of `Mavsdk` to its own scope, so the instantiation changes as follows:
+
+Old instantiation:
+```
+Mavsdk mavsdk{Mavsdk::Configuration{Mavsdk::ComponentType::GroundStation}};
+```
+
+New instantiation:
+```
+Mavsdk mavsdk{Mavsdk::Configuration{ComponentType::GroundStation}};
+```
+
+### Camera plugin: major redesign
+
+The camera plugin API and internals have changed considerably. The aim was to be able to address multiple cameras from one plugin which enables more than one camera to be used in language wrappers such as Python. This wasn't previously possible.
+
+Moreover, we now support MAVLink FTP and https to download the camera definition files, and not just http:
+
+The API has changed to include a camera ID. Below is an example how usage changes:
+
+```
+
+auto camera = Camera{system};
+camera.select_camera(0);
+
+auto result = camera.zoom_range(component_id, 2.0f);
+```
+
+To:
+
+```
+auto camera = Camera{system};
+
+// Assuming one camera is connected:
+assert(camera.camera_list().cameras.size() == 1);
+auto component_id = camera.camera_list().cameras[0].component_id;
+
+auto result = camera.zoom_range(component_id, 2.0f);
+```
+
+### Rtk and LogStreaming plugins: base64 for binary data
+
+With v2 it was hard or impossible to use APIs involving binary data in certain language wrappers, specifically Python. This meant that the RTK corrections and log streaming data were exposed as Python strings which didn't match the binary nature of the data.
+
+Therefore, we are now using base64 for the data.
+
+The assumption is that the performance hit of having to encode to and decode from base64 is negligible on platforms where MAVSDK is usually run.
+
+Mavsdk provides helper functions to help with encoding and decoding base64:
+
+```
+#include <mavsdk/base64.h>
+
+std::string encoded = ...;
+std::vector<uint8_t> binary_data = base64_decode(encoded);
+```
+
 ## v2
 
 ### Mavsdk configuration
@@ -97,7 +203,7 @@ For instance a camera server plugin can be used as follows:
 
 ```
 Mavsdk mavsdk{Mavsdk::Configuration{Mavsdk::ComponentType::Camera}};
-auto camera_server = mavsdk::CameraServer{mavsdk.server_component()};
+auto camera_server = CameraServer{mavsdk.server_component()};
 ```
 
 It's also possible to add more than one MAVLink component to one MAVSDK instance, e.g. a gimbal could be added like this: