Merge branch 'main' into 14-add-a-class-for-udp-client

Author: eigen-value

README.md

@@ -5,7 +5,8 @@ In this repo it will be implemented an Arduino library wrapper for RPClite to be
 Including Arduino_RouterBridge.h gives the user access to a Bridge object that can be used both as a RPC client and/or server to execute and serve RPCs to/from the CPU Host running a GOLANG router.
 
 - The Bridge object is pre-defined on Serial1 and automatically initialized inside the main setup()
-- The Bridge.call method is blocking and works the same as in RPClite
+- The Bridge.call method is non-blocking and returns a RpcResult async object
+- RpcResult class implements a blocking .result method that waits for the RPC response and returns true if the RPC returned with no errors
 - The Bridge can provide callbacks to incoming RPC requests both in a thread-unsafe and thread-safe fashion (provide & provide_safe)
 - Thread-safe methods execution is granted in the main loop thread where update_safe is called. By design users cannot access .update_safe() freely
 - Thread-unsafe methods are served in an update callback, whose execution is granted in a separate thread. Nonetheless users can access .update() freely with caution
@@ -24,29 +25,50 @@ String greet() {
 }
 
 void setup() {
-    Serial.begin(115200);
-    while (!Serial);
-    
+
+    Bridge.begin();
+    Monitor.begin();
+
     pinMode(LED_BUILTIN, OUTPUT);
 
     if (!Bridge.provide("set_led", set_led)) {
-        Serial.println("Error providing method: set_led");
+        Monitor.println("Error providing method: set_led");
     } else {
-        Serial.println("Registered method: set_led");
+        Monitor.println("Registered method: set_led");
     }
 
     Bridge.provide_safe("greet", greet);
 
 }
 
 void loop() {
-    float res;
-    if (!Bridge.call("multiply", res, 1.0, 2.0)) {
-        Serial.println("Error calling method: multiply");
-        Serial.println(Bridge.get_error_code());
-        Serial.println(Bridge.get_error_message());
+    float sum;
+
+    // CALL EXAMPLES
+
+    // Standard chained call: Bridge.call("method", params...).result(res)
+    if (!Bridge.call("add", 1.0, 2.0).result(sum)) {
+        Monitor.println("Error calling method: add");
+    };
+
+    // Async call
+    RpcResult async_rpc = Bridge.call("add", 3.0, 4.5);
+    if (!async_rpc.result(sum)) {
+        Monitor.println("Error calling method: add");
+        Monitor.print("Error code: ");
+        Monitor.println(async_rpc.error.code);
+        Monitor.print("Error message: ");
+        Monitor.println(async_rpc.error.traceback);
+    }
+
+    // Implicit boolean cast. Use with caution as in this case the call is indeed
+    // executed expecting a fallback nil result (MsgPack::object::nil_t)
+    if (!Bridge.call("send_greeting", "Hello Friend")) {
+        Monitor.println("Error calling method: send_greeting");
     };
 
+    // Please use notify when no reult (None, null, void, nil etc.) is expected from the opposite side
+    // the following is executed immediately
     Bridge.notify("signal", 200);
 }
 ```

examples/simple_bridge/simple_bridge.ino

@@ -47,11 +47,23 @@ void setup() {
 
 void loop() {
     float res;
-    if (!Bridge.call("multiply", res, 1.0, 2.0)) {
+    if (!Bridge.call("multiply", 1.0, 2.0).result(res)) {
         Serial.println("Error calling method: multiply");
         Serial.println(Bridge.get_error_code());
         Serial.println(Bridge.get_error_message());
     };
 
+    // Call with deferred response check
+    RpcResult outcome = Bridge.call("multiply", 5.0, 7.0);
+    Serial.println("RPC called");
+    delay(10);
+    if (outcome.result(res)) {
+        Serial.print("Result of the operation is: ");
+        Serial.println(res);
+    } else {
+        Serial.println(Bridge.get_error_code());
+        Serial.println(Bridge.get_error_message());
+    }
+
     Bridge.notify("signal", 200);
 }

examples/test/python/main.py

@@ -0,0 +1,39 @@
+import time
+from arduino.app_utils import *
+
+
+def no_args_no_result():
+    print("0 args no result")
+    return
+
+def no_args_bool_result():
+    print("0 args bool result")
+    return True
+
+def one_args_float_result(a):
+    print("1 args float result")
+    return a^2
+
+def two_args_float_result(a, b):
+    print("2 args float result")
+    return a/b
+
+def one_args_no_result(msg: str):
+    print("1 args no result")
+    print(f"Message received: {msg}")
+
+def two_args_no_result(msg: str, x: int):
+    print("2 args no result")
+    print(f"Message received: {msg} {str(x)}")
+
+
+if __name__ == "__main__":
+
+    Bridge.provide("0_args_no_result", no_args_no_result)
+    Bridge.provide("0_args_bool_result", no_args_bool_result)
+    Bridge.provide("1_args_float_result", one_args_float_result)
+    Bridge.provide("2_args_float_result", two_args_float_result)
+    Bridge.provide("1_args_no_result", one_args_no_result)
+    Bridge.provide("2_args_no_result", two_args_no_result)
+
+    App.run()

examples/test/test.ino

@@ -0,0 +1,102 @@
+/*
+    This file is part of the Arduino_RouterBridge library.
+
+    Copyright (c) 2025 Arduino SA
+
+    This Source Code Form is subject to the terms of the Mozilla Public
+    License, v. 2.0. If a copy of the MPL was not distributed with this
+    file, You can obtain one at http://mozilla.org/MPL/2.0/.
+    
+*/
+
+
+#include "Arduino_RouterBridge.h"
+
+bool x;
+int i=0;
+
+void setup() {
+   Bridge.begin();
+   Monitor.begin();
+}
+
+void loop() {
+
+    // testing monitor
+    Monitor.println("\r\n"+String(i));
+    i++;
+
+    // working
+    Bridge.call("0_args_no_result");
+
+    if (Bridge.call("0_args_no_result")){
+      Monitor.println("0_args_no_result TRUE without result"); // returns true because there's no result
+    }
+    else{
+      Monitor.println("0_args_no_result FALSE without result");
+    }
+
+    if (Bridge.call("0_args_bool_result")){
+      Monitor.println("0_args_bool_result TRUE without result");
+    }
+    else{
+      Monitor.println("0_args_bool_result FALSE without result"); // returns false -> check the result
+    }
+
+    x = false;
+    if (Bridge.call("0_args_bool_result").result(x)){
+      Monitor.println("0_args_bool_result TRUE with result: "+String(x)); // returns true - the perfect call
+    }
+    else{
+      Monitor.println("0_args_bool_result FALSE witt result: "+String(x));
+    }
+
+    int y = -1;
+    if (Bridge.call("0_args_bool_result").result(y)){
+      Monitor.println("0_args_bool_result TRUE with result: "+String(y)+" (wrong result type)");
+    }
+    else {
+      Monitor.println("0_args_bool_result FALSE with result: "+String(y)+" (wrong result type)"); // returns false - wrong type
+    }
+
+    float pow;
+    RpcResult async_res = Bridge.call("1_args_float_result", 2.0, 3.0);  // passing 2 args to a function expecting 1
+    if (async_res.result(pow)) {
+      Monitor.println("Result of assignment and then result: "+String(pow)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res.error.code));
+      Monitor.println("Error message: "+async_res.error.traceback);
+    }
+
+    float div = 0;
+    RpcResult async_res1 = Bridge.call("2_args_float_result", 2.0);  // passing 1 arg when 2 are expected
+    if (async_res1.result(div)) {
+      Monitor.println("Result of assignment and then result: "+String(div)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res1.error.code));
+      Monitor.println("Error message: "+async_res1.error.traceback);
+    }
+
+    div = 0;
+    RpcResult async_res2 = Bridge.call("2_args_float_result", 2.0, "invalid");  // passing a wrong type arg
+    if (async_res2.result(div)) {
+      Monitor.println("Result of assignment and then result: "+String(div)); // returns true, so the right result
+    } else {
+      Monitor.println("Error code: "+String(async_res2.error.code));
+      Monitor.println("Error message: "+async_res2.error.traceback);
+    }
+
+    x = false;
+    RpcResult async_res3 = Bridge.call("0_args_bool_result");
+    if (async_res3.result(x)) {
+        Monitor.println("Result of assignment and then result: "+String(x)); // returns true, so the right result
+    } else {
+        Monitor.println("Error expecting bool result: "+String(async_res3.error.code));
+    }
+
+    // Avoid the following:
+    // the call happens in the destructor falling back to the "no_result" case (a type mismatch here)
+    RpcResult async_res4 = Bridge.call("0_args_bool_result");
+
+    delay(1000);
+}

library.json

@@ -11,7 +11,7 @@
     "url": "https://github.com/bcmi-labs/Arduino_RouterBridge",
     "maintainer": true
   },
-  "version": "0.1.4",
+  "version": "0.2.1",
   "license": "MPL2.0",
   "frameworks": "arduino",
   "platforms": "*",

library.properties

@@ -1,5 +1,5 @@
 name=Arduino_RouterBridge
-version=0.1.4
+version=0.2.1
 author=BCMI-labs
 maintainer=BCMI-labs
 sentence=A RPC bridge for Arduino UNO Q boards