Update the Giga RPC/dual-core tutorial.

Add a section on using the RPC library with MicroPython.

Signed-off-by: iabdalkader <[email protected]>

Author: iabdalkader

content/hardware/10.mega/boards/giga-r1-wifi/tutorials/giga-dual-core/giga-dual-core.md

@@ -24,7 +24,8 @@ The M4 and M7 cores are programmed with separate sketches, using the same serial
 In this guide you will discover:
 - How to configure and program the M4/M7 cores and conventional approaches to do so.
 - How to boot the M4 core.
-- How to communicate between the cores via Remote Call Procedures (RPC).
+- How to communicate between the cores via Remote Procedure Call (RPC).
+- Using the RPC Library with MicroPython.
 - Useful examples based on the dual core & RPC features.
 - The `RPC` library API.
 
@@ -194,7 +195,7 @@ void blink(int led, int delaySeconds) {
 - The `CM7_CPUID` flag that we compare with holds the value `0x00000003` (hexadecimal), or `3` (decimal).
 - It is also possible to use `CM4_CPUID` flag which holds the value `0x00000003`, or `1` (decimal).
 
-## Remote Call Procedures (RPC)
+## Remote Procedure Call (RPC)
 
 RPC is a method that allows programs to make requests to programs located elsewhere. It is based on the client-server model (also referred to as caller/callee), where the client makes a request to the server. 
 
@@ -226,7 +227,8 @@ RPC.bind("addFunction", addFunction);
 On the client side, it could look like this:
 
 ```arduino
-int x,y = 10;
+int x = 10;
+int y = 10;
 
 RPC.call("addFunction", x, y);
 ```
@@ -235,6 +237,103 @@ When `call()` is used, a request is sent, it is processed on the server side, an
 
 ![Communication between M7 and M4 core.](assets/rpc-m7-m4.png)
 
+### Using the RPC Library with MicroPython
+
+The `msgpackrpc` library provides the same functionality as the Arduino RPC library for MicroPython, i.e., it allows the binding of local functions or objects, starting the M4 core, and invoking remote calls from Python scripts. This library and its supporting features are enabled by default on all compatible Arduino boards starting with MicroPython release 1.23 and require no external dependencies to use. Additionally, the Arduino sketches presented in the examples section here require no changes to use with MicroPython. However, there are a few restrictions to using the RPC library with MicroPython. The first one is that MicroPython firmware always targets the main M7 core, consequently, Arduino sketches can only run on the M4 core. Additionally, only flash-based firmware, with the `1.5MB M7 + 0.5MB M4` flash partitioning scheme, is supported. While the `msgpackrpc` library does support loading firmware images to any address space, the firmware currently generated for the M4 core with an SDRAM target does not work. This issue may be fixed in future releases.
+
+The following sections introduce the `msgpackrpc` library API and some use cases in detail.
+
+#### The `msgpackrpc` Library
+
+The `msgpackrpc` library is the RPC library's counterpart for MicroPython, and it provides the same functionality as the Arduino RPC library. The first steps to using the `msgpackrpc` library, are importing the module and creating a `MsgPackRPC` object:
+
+```python
+import msgpackrpc
+
+# Create a MsgPackRPC object.
+rpc = msgpackrpc.MsgPackRPC()
+```
+
+The RPC object created above can then be used to bind Python callables, start the M4 core and invoke remote calls from MicroPython scripts.
+
+#### Binding Python Functions, Callables and Objects
+
+The next step is binding callables. Any Python callable (such as functions, bound methods, callable objects etc..) can be bound to a name and be made available to the remote core to call. The following example binds a function to the name `sub`:
+
+```python
+def sub(a, b):
+    return a - b
+
+# Register a function to be called by the remote processor.
+rpc.bind("sub", sub)
+```
+
+Similarly, an object's bound method can also be bound to a name. For example:
+
+```python
+foo = Foo()
+rpc.bind("sub", foo.add)
+```
+
+Both of those functions can be called in the same way from the Arduino sketch:
+
+```arduino
+int res = RPC.call("sub", 2, 1).as<int>();
+```
+
+Objects can also be bound to allow their methods to be called by the remote core. When an object is passed to `bind()`, all of its public methods (the ones that don't start with an `_`) are bound to their respective qualified names. For example, the following code binds the methods of an object of class `Foo`:
+
+```python
+class Foo:
+    def __init__(self):
+        pass
+
+    def add(a, b):
+        return a + b
+
+    def sub(a, b):
+        return a - b
+
+# Register an object of Foo
+rpc.bind("foo1", Foo())
+```
+
+Now the object's methods can be invoked by the Arduino sketch using their fully qualified name, for example:
+
+```arduino
+int res1 = RPC.call("foo1.add", 1, 2).as<int>();
+int res2 = RPC.call("foo1.sub", 2, 1).as<int>();
+```
+
+#### Starting the M4 Core From Micropython
+
+The next step is starting the M4 core by calling `MsgPackRPC.start()` with the firmware entry point as an argument:
+
+```python
+# Start the remote processor and wait for it to be ready to communicate.
+rpc.start(firmware=0x08180000)
+```
+
+This function will start the remote core (the M4), boot it from the specified firmware address, and wait for the core to be ready to communicate before it returns. The default arguments passed to this function are compatible with the Arduino RPC library and do not need to be changed for the purposes of this tutorial. Note that the firmware address used is a flash address, where the M4 firmware starts, and it's the same one used for the flash split of `1.5MB M7 + 0.5MB M4`.
+
+#### Calling Remote Functions From Micropython
+
+Once the M4 core is started, the `MsgPackRPC` object can be used to invoke its remote functions. Remote calls can be invoked synchronously, i.e., the call does not return until a response is received from the other side, or asynchronously. In this case, the call returns a `Future` object that must be joined at some point to read back the call's return value.
+
+```python
+# Perform a synchronous call, which blocks until it returns.
+res = rpc.call("add", 1, 2)
+
+# Perform an asynchronous call, which returns immediately with a Future object.
+f1 = rpc.call_async("add", 1, 2)
+
+# The Future object returned above, must be joined at some point to get the results.
+print(f1.join())
+```
+
+That covered most of the `msgpackrpc` library's API and use cases. For a complete example, see the [MicroPython RPC LED Example](#micropython-rpc-led). For more examples and applications, see the `msgpackrpc` [repository](https://github.com/arduino/arduino-lib-mpy/tree/main/lib/msgpackrpc).
+
+
 ## RPC Examples
 
 In this section, you will find a series of examples that is based on the `RPC` library. 
@@ -251,12 +350,12 @@ The `Serial.print()` command only works on the **M7 core**. In order to print va
 #include <RPC.h>
 
 void setup() {
-RPC.begin();
+  RPC.begin();
 }
 
 void loop() {
-RPC.println("Printed from M4 core");
-delay(1000);
+  RPC.println("Printed from M4 core");
+  delay(1000);
 }
 ```
 
@@ -266,8 +365,8 @@ delay(1000);
 #include <RPC.h>
 
 void setup() {
-Serial.begin(9600);
-RPC.begin();
+  Serial.begin(9600);
+  RPC.begin();
 }
 
 void loop() {
@@ -308,6 +407,7 @@ void setup() {
 }
 
 void loop() {
+
 }
 
 /*
@@ -454,6 +554,53 @@ int servoMove(int angle) {
 }
 ```
 
+### MicroPython RPC LED
+
+This example demonstrates how to use MicroPython (running on the M7 core) to remotely control an LED connected to the M4 core.
+
+**M4 sketch:**
+
+```arduino
+#include "RPC.h"
+
+void led(bool on) {
+  if (on) {
+    digitalWrite(LEDG, LOW);
+  } else {
+    digitalWrite(LEDG, HIGH);
+  }
+}
+
+void setup() {
+  RPC.bind("led", led);
+  RPC.begin();
+}
+
+void loop() {
+
+}
+```
+
+**M7 Python script:**
+
+```python
+import time
+import msgpackrpc
+
+# Create an RPC object
+rpc = msgpackrpc.MsgPackRPC()
+
+# Start the remote processor.
+rpc.start(firmware=0x08180000)
+
+# Toggle the LED every 500ms
+while True:
+    rpc.call("led", True)
+    time.sleep_ms(500)
+    rpc.call("led", False)
+    time.sleep_ms(500)
+```
+
 ## RPC Library API
 
 The `RPC` library is based on the [rpclib](https://github.com/rpclib/rpclib) C++ library which provides a client and server implementation. In addition, it provides a method for communication between the M4 and M7 cores. 
@@ -575,4 +722,4 @@ RPC.read();
 #### Returns
 
 - The first available byte from the M4.
-- `-1` if there is none.
+- `-1` if there is none.