core: fixup API naming and docs

This should make the raw connection a bit clearer.

Author: julianoes

docs/en/cpp/api_reference/classmavsdk_1_1_mavsdk.md

@@ -66,9 +66,9 @@ void | [unsubscribe_incoming_messages_json](#classmavsdk_1_1_mavsdk_1a4be244c389
 void | [unsubscribe_outgoing_messages_json](#classmavsdk_1_1_mavsdk_1aa3a490358db87cfed617cdad902bb753) ([InterceptJsonHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1a3b40ae4fd8af4c4419b61f0ad955812f) handle) | Unsubscribe from outgoing messages as JSON.
 void | [intercept_incoming_messages_async](#classmavsdk_1_1_mavsdk_1ac80c8909958533131cbdbc61d061794f) (std::function< bool(mavlink_message_t &)> callback) | Intercept incoming messages.
 void | [intercept_outgoing_messages_async](#classmavsdk_1_1_mavsdk_1a040ee5c1d41e71c0d63cf8f76d2db275) (std::function< bool(mavlink_message_t &)> callback) | Intercept outgoing messages.
-bool | [send_raw_bytes](#classmavsdk_1_1_mavsdk_1a59d76dd05fc7dacc949a607d16cf3221) (const char * bytes, size_t length) | Send raw MAVLink bytes.
-[RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) | [subscribe_raw_bytes](#classmavsdk_1_1_mavsdk_1a377715955e2fd52c1caa960ebe208a57) ([RawBytesCallback](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1acb5be9a1be97d251387ffe87ae8b9eb0) callback) | Subscribe to all outgoing raw bytes.
-void | [unsubscribe_raw_bytes](#classmavsdk_1_1_mavsdk_1a19f57749bf10aca6512ad2cbe07c33ab) ([RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) handle) | Unsubscribe from raw bytes.
+void | [pass_received_raw_bytes](#classmavsdk_1_1_mavsdk_1a65329315ac07bae110839d9e054fbc05) (const char * bytes, size_t length) | Pass received raw MAVLink bytes.
+[RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) | [subscribe_raw_bytes_to_be_sent](#classmavsdk_1_1_mavsdk_1a116e9bab0efdf7ec90866107ef517b20) ([RawBytesCallback](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1acb5be9a1be97d251387ffe87ae8b9eb0) callback) | Subscribe to raw bytes to be sent.
+void | [unsubscribe_raw_bytes_to_be_sent](#classmavsdk_1_1_mavsdk_1af6ec813a9728f4258056fa1f5d399eb1) ([RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) handle) | Unsubscribe from raw bytes to be sent.
 
 
 ## Constructor & Destructor Documentation
@@ -611,45 +611,45 @@ This functionality is provided primarily for testing in order to simulate packet
 
 * std::function< bool(mavlink_message_t &)> **callback** - Callback to be called for each outgoing message. To drop a message, return 'false' from the callback.
 
-### send_raw_bytes() {#classmavsdk_1_1_mavsdk_1a59d76dd05fc7dacc949a607d16cf3221}
+### pass_received_raw_bytes() {#classmavsdk_1_1_mavsdk_1a65329315ac07bae110839d9e054fbc05}
 ```cpp
-bool mavsdk::Mavsdk::send_raw_bytes(const char *bytes, size_t length)
+void mavsdk::Mavsdk::pass_received_raw_bytes(const char *bytes, size_t length)
 ```
 
 
-Send raw MAVLink bytes.
+Pass received raw MAVLink bytes.
 
-This allows sending raw MAVLink message bytes through all connections. The bytes can contain one or more MAVLink messages.
+This allows passing raw MAVLink message bytes into MAVSDK to be processel. The bytes can contain one or more MAVLink messages.
 
 
 ::: info
-When this API is first used, heartbeats will be automatically enabled.
+Before using this, run add_any_connection("raw://")
 :::
 
+This goes together with subscribe_to_bytes_to_send.
+
 **Parameters**
 
 * const char\* **bytes** - Pointer to raw MAVLink message bytes.
 * size_t **length** - Number of bytes to send.
 
-**Returns**
-
-&emsp;bool - true if bytes were successfully sent, false otherwise.
-
-### subscribe_raw_bytes() {#classmavsdk_1_1_mavsdk_1a377715955e2fd52c1caa960ebe208a57}
+### subscribe_raw_bytes_to_be_sent() {#classmavsdk_1_1_mavsdk_1a116e9bab0efdf7ec90866107ef517b20}
 ```cpp
-RawBytesHandle mavsdk::Mavsdk::subscribe_raw_bytes(RawBytesCallback callback)
+RawBytesHandle mavsdk::Mavsdk::subscribe_raw_bytes_to_be_sent(RawBytesCallback callback)
 ```
 
 
-Subscribe to all outgoing raw bytes.
+Subscribe to raw bytes to be sent.
 
-This allows monitoring all MAVLink bytes that are sent out through any connection. The callback will be called with raw bytes after they are successfully sent.
+This allows getting MAVLink bytes that need to be sent out.
 
 
 ::: info
-When this API is first used, heartbeats will be automatically enabled.
+Before using this, run add_any_connection("raw://")
 :::
 
+This goes together with pass_received_raw_bytes. The bytes contain one mavlink message at a time.
+
 **Parameters**
 
 * [RawBytesCallback](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1acb5be9a1be97d251387ffe87ae8b9eb0) **callback** - Callback to be called with outgoing raw bytes.
@@ -658,15 +658,15 @@ When this API is first used, heartbeats will be automatically enabled.
 
 &emsp;[RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) - [Handle](classmavsdk_1_1_handle.md) to unsubscribe again.
 
-### unsubscribe_raw_bytes() {#classmavsdk_1_1_mavsdk_1a19f57749bf10aca6512ad2cbe07c33ab}
+### unsubscribe_raw_bytes_to_be_sent() {#classmavsdk_1_1_mavsdk_1af6ec813a9728f4258056fa1f5d399eb1}
 ```cpp
-void mavsdk::Mavsdk::unsubscribe_raw_bytes(RawBytesHandle handle)
+void mavsdk::Mavsdk::unsubscribe_raw_bytes_to_be_sent(RawBytesHandle handle)
 ```
 
 
-Unsubscribe from raw bytes.
+Unsubscribe from raw bytes to be sent.
 
 
 **Parameters**
 
-* [RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) **handle** - [Handle](classmavsdk_1_1_handle.md) from subscribe_raw_bytes.
+* [RawBytesHandle](classmavsdk_1_1_mavsdk.md#classmavsdk_1_1_mavsdk_1ac766258f137aa3e8b0dabb5a66435ea1) **handle** - [Handle](classmavsdk_1_1_handle.md) from subscribe_raw_bytes_to_be_sent.

src/mavsdk/core/include/mavsdk/mavsdk.h

@@ -474,38 +474,41 @@ class Mavsdk {
     using RawBytesHandle = Handle<const char*, size_t>;
 
     /**
-     * @brief Send raw MAVLink bytes.
+     * @brief Pass received raw MAVLink bytes.
      *
-     * This allows sending raw MAVLink message bytes through all connections.
+     * This allows passing raw MAVLink message bytes into MAVSDK to be processel.
      * The bytes can contain one or more MAVLink messages.
      *
-     * @note When this API is first used, heartbeats will be automatically enabled.
+     * @note Before using this, run add_any_connection("raw://")
+     *
+     * This goes together with subscribe_to_bytes_to_send.
      *
      * @param bytes Pointer to raw MAVLink message bytes.
      * @param length Number of bytes to send.
-     * @return true if bytes were successfully sent, false otherwise.
      */
-    bool send_raw_bytes(const char* bytes, size_t length);
+    void pass_received_raw_bytes(const char* bytes, size_t length);
 
     /**
-     * @brief Subscribe to all outgoing raw bytes.
+     * @brief Subscribe to raw bytes to be sent.
+     *
+     * This allows getting MAVLink bytes that need to be sent out.
      *
-     * This allows monitoring all MAVLink bytes that are sent out through any connection.
-     * The callback will be called with raw bytes after they are successfully sent.
+     * @note Before using this, run add_any_connection("raw://")
      *
-     * @note When this API is first used, heartbeats will be automatically enabled.
+     * This goes together with pass_received_raw_bytes.
+     * The bytes contain one mavlink message at a time.
      *
      * @param callback Callback to be called with outgoing raw bytes.
      * @return Handle to unsubscribe again.
      */
-    RawBytesHandle subscribe_raw_bytes(RawBytesCallback callback);
+    RawBytesHandle subscribe_raw_bytes_to_be_sent(RawBytesCallback callback);
 
     /**
-     * @brief Unsubscribe from raw bytes.
+     * @brief Unsubscribe from raw bytes to be sent.
      *
-     * @param handle Handle from subscribe_raw_bytes.
+     * @param handle Handle from subscribe_raw_bytes_to_be_sent.
      */
-    void unsubscribe_raw_bytes(RawBytesHandle handle);
+    void unsubscribe_raw_bytes_to_be_sent(RawBytesHandle handle);
 
 private:
     static constexpr int DEFAULT_SYSTEM_ID_AUTOPILOT = 1;

src/mavsdk/core/mavsdk.cpp

@@ -234,19 +234,19 @@ void Mavsdk::intercept_outgoing_messages_async(std::function<bool(mavlink_messag
     _impl->intercept_outgoing_messages_async(callback);
 }
 
-bool Mavsdk::send_raw_bytes(const char* bytes, size_t length)
+void Mavsdk::pass_received_raw_bytes(const char* bytes, size_t length)
 {
-    return _impl->send_raw_bytes(bytes, length);
+    _impl->pass_received_raw_bytes(bytes, length);
 }
 
-Mavsdk::RawBytesHandle Mavsdk::subscribe_raw_bytes(RawBytesCallback callback)
+Mavsdk::RawBytesHandle Mavsdk::subscribe_raw_bytes_to_be_sent(RawBytesCallback callback)
 {
-    return _impl->subscribe_raw_bytes(callback);
+    return _impl->subscribe_raw_bytes_to_be_sent(callback);
 }
 
-void Mavsdk::unsubscribe_raw_bytes(RawBytesHandle handle)
+void Mavsdk::unsubscribe_raw_bytes_to_be_sent(RawBytesHandle handle)
 {
-    _impl->unsubscribe_raw_bytes(handle);
+    _impl->unsubscribe_raw_bytes_to_be_sent(handle);
 }
 
 Mavsdk::ConnectionErrorHandle

src/mavsdk/core/mavsdk_impl.cpp

@@ -1373,20 +1373,20 @@ RawConnection* MavsdkImpl::find_raw_connection()
     return nullptr;
 }
 
-bool MavsdkImpl::send_raw_bytes(const char* bytes, size_t length)
+void MavsdkImpl::pass_received_raw_bytes(const char* bytes, size_t length)
 {
     auto* raw_conn = find_raw_connection();
     if (raw_conn == nullptr) {
         LogErr()
             << "No raw connection available. Please add one using add_any_connection(\"raw://\")";
-        return false;
+        return;
     }
 
     raw_conn->receive(bytes, length);
-    return true;
 }
 
-Mavsdk::RawBytesHandle MavsdkImpl::subscribe_raw_bytes(const Mavsdk::RawBytesCallback& callback)
+Mavsdk::RawBytesHandle
+MavsdkImpl::subscribe_raw_bytes_to_be_sent(const Mavsdk::RawBytesCallback& callback)
 {
     if (find_raw_connection() == nullptr) {
         LogWarn() << "No raw connection available. Subscription will only receive bytes after you "
@@ -1395,7 +1395,7 @@ Mavsdk::RawBytesHandle MavsdkImpl::subscribe_raw_bytes(const Mavsdk::RawBytesCal
     return _raw_bytes_subscriptions.subscribe(callback);
 }
 
-void MavsdkImpl::unsubscribe_raw_bytes(Mavsdk::RawBytesHandle handle)
+void MavsdkImpl::unsubscribe_raw_bytes_to_be_sent(Mavsdk::RawBytesHandle handle)
 {
     _raw_bytes_subscriptions.unsubscribe(handle);
 }

src/mavsdk/core/mavsdk_impl.h

@@ -103,9 +103,9 @@ class MavsdkImpl {
     void unsubscribe_connection_errors(Mavsdk::ConnectionErrorHandle handle);
 
     // Raw bytes API
-    bool send_raw_bytes(const char* bytes, size_t length);
-    Mavsdk::RawBytesHandle subscribe_raw_bytes(const Mavsdk::RawBytesCallback& callback);
-    void unsubscribe_raw_bytes(Mavsdk::RawBytesHandle handle);
+    void pass_received_raw_bytes(const char* bytes, size_t length);
+    Mavsdk::RawBytesHandle subscribe_raw_bytes_to_be_sent(const Mavsdk::RawBytesCallback& callback);
+    void unsubscribe_raw_bytes_to_be_sent(Mavsdk::RawBytesHandle handle);
     bool notify_raw_bytes_sent(const char* bytes, size_t length);
 
     std::shared_ptr<ServerComponent> server_component(unsigned instance = 0);

src/system_tests/raw_bytes.cpp

@@ -23,28 +23,29 @@ TEST(SystemTest, RawBytesHeartbeat)
     bool heartbeat_received = false;
 
     // Subscribe to raw bytes to capture the heartbeat response
-    auto handle = mavsdk_responder.subscribe_raw_bytes([&prom, &heartbeat_received](
-                                                           const char* bytes, size_t length) {
-        LogInfo() << "Received " << length << " raw bytes";
+    auto handle = mavsdk_responder.subscribe_raw_bytes_to_be_sent(
+        [&prom, &heartbeat_received](const char* bytes, size_t length) {
+            LogInfo() << "Received " << length << " raw bytes";
 
-        // Parse to check if this is a heartbeat
-        mavlink_message_t msg = {};
-        mavlink_status_t status = {};
+            // Parse to check if this is a heartbeat
+            mavlink_message_t msg = {};
+            mavlink_status_t status = {};
 
-        for (size_t i = 0; i < length; ++i) {
-            if (mavlink_parse_char(MAVLINK_COMM_0, static_cast<uint8_t>(bytes[i]), &msg, &status)) {
-                if (msg.msgid == MAVLINK_MSG_ID_HEARTBEAT) {
-                    LogInfo() << "Captured HEARTBEAT message from system " << (int)msg.sysid
-                              << ", component " << (int)msg.compid;
-                    if (!heartbeat_received) {
-                        heartbeat_received = true;
-                        prom.set_value();
+            for (size_t i = 0; i < length; ++i) {
+                if (mavlink_parse_char(
+                        MAVLINK_COMM_0, static_cast<uint8_t>(bytes[i]), &msg, &status)) {
+                    if (msg.msgid == MAVLINK_MSG_ID_HEARTBEAT) {
+                        LogInfo() << "Captured HEARTBEAT message from system " << (int)msg.sysid
+                                  << ", component " << (int)msg.compid;
+                        if (!heartbeat_received) {
+                            heartbeat_received = true;
+                            prom.set_value();
+                        }
+                        return;
                     }
-                    return;
                 }
             }
-        }
-    });
+        });
 
     // Give subscription time to be registered
     std::this_thread::sleep_for(std::chrono::milliseconds(100));
@@ -71,7 +72,7 @@ TEST(SystemTest, RawBytesHeartbeat)
     std::thread heartbeat_thread([&]() {
         while (should_send_heartbeats) {
             LogInfo() << "Sending raw heartbeat (" << len << " bytes)...";
-            mavsdk_responder.send_raw_bytes(
+            mavsdk_responder.pass_received_raw_bytes(
                 reinterpret_cast<const char*>(heartbeat_bytes.data()), len);
             std::this_thread::sleep_for(std::chrono::seconds(1));
         }
@@ -87,5 +88,5 @@ TEST(SystemTest, RawBytesHeartbeat)
     should_send_heartbeats = false;
     heartbeat_thread.join();
 
-    mavsdk_responder.unsubscribe_raw_bytes(handle);
+    mavsdk_responder.unsubscribe_raw_bytes_to_be_sent(handle);
 }