Merge pull request #2770 from arduino/mcmchris/uno-q/rpc-doc

[PXCT-1614] Router + RPC Documentation Extended in User Manual

Author: mcmchris

content/hardware/02.uno/boards/uno-q/tutorials/01.user-manual/assets/custom-python-rpc.png

@@ -821,7 +821,7 @@ The `Bridge` library provides a communication layer built on top of the `Arduino
 
 #### The Arduino Router (Infrastructure)
 
-Under the hood, the communication is managed by a background Linux service called the Arduino Router (`arduino-router`).
+Under the hood, the communication is managed by a background Linux service called the **Arduino Router** (`arduino-router`).
 
 While the `Bridge` library is what you use in your code, the Router is the traffic controller that makes it possible. It implements a **Star Topology** network using MessagePack RPC.
 
@@ -835,7 +835,22 @@ While the `Bridge` library is what you use in your code, the Router is the traff
 
 - **Service Discovery:** Clients (like your Python® script or the MCU Sketch) "register" functions they want to expose. The Router keeps a directory of these functions and routes calls to the correct destination.
 
-**Managing the Router Service**
+**Source Code:**
+
+- **[Arduino Router Service](https://github.com/arduino/arduino-router)**
+- **[Arduino_RouterBridge Library](https://github.com/arduino-libraries/Arduino_RouterBridge/tree/main)**
+
+#### System Configuration & Hardware Interfaces
+
+The Router manages the physical connection between the two processors. It is important to know which hardware resources are claimed by the Router to avoid conflicts in your own applications.
+
+* **Linux Side (MPU):** The router claims the serial device `/dev/ttyHS1`.
+* **MCU Side (STM32):** The router claims the hardware serial port `Serial1`.
+
+> **⚠️ WARNING: Reserved Resources**
+> Do not attempt to open `/dev/ttyHS1` (on Linux) or `Serial1` (on Arduino/Zephyr) in your own code. These interfaces are exclusively locked by the `arduino-router` service. Attempting to access them directly will cause the Bridge to fail.
+
+#### Managing the Router Service
 
 The arduino-router runs automatically as a system service. In most cases, you do not need to interact with it directly. However, if you are debugging advanced issues or need to restart the communication stack, you can control it via the Linux terminal:
 
@@ -923,7 +938,7 @@ To capture more detailed information in the logs, you can append the `--verbose`
 - **Incoming Updates**: Handled by a dedicated background thread (`updateEntryPoint`) that continuously polls for requests.
 - **Safe Execution**: The provide_safe mechanism hooks into the main loop (`__loopHook`) to execute user callbacks safely when the processor is idle.
 
-#### Usage Example
+#### Usage Example (Arduino App Lab)
 
 This example shows the **Linux side (Qualcomm QRB)** toggling an LED on the **MCU (STM32)** by calling a remote function over the Bridge.
 
@@ -984,6 +999,117 @@ After pasting the Python script into your App’s Python file and the Arduino co
 
 ***There are more advanced methods in the Bridge RPC library that you can discover by testing our different built-in examples inside Arduino App Lab.***
 
+#### Interacting via Unix Socket (Advanced)
+
+Linux processes communicate with the Router using a **Unix Domain Socket** located at:
+`/var/run/arduino-router.sock`
+
+While the `Bridge` library handles this automatically for you, you can manually connect to this socket to interact with the MCU or other Linux services using any language that supports **MessagePack RPC** (e.g., Python, C++, Rust, Go).
+
+#### Usage Example (Custom Python Client)
+
+The following example demonstrates how to control an MCU function (`set_led_state`) from a standard Python script using the `msgpack` library, without using the Arduino App Lab helper classes. This is useful for integrating Arduino functions into existing Linux applications.
+
+**Prerequisites:**
+
+1. **Flash the MCU Sketch**
+   
+   Upload the following code using the Arduino IDE or Arduino App Lab. This registers the function we want to call.
+
+    ```cpp
+    #include "Arduino_RouterBridge.h"
+
+    void setup() {
+      pinMode(LED_BUILTIN, OUTPUT);
+
+      Bridge.begin();
+      // We use provide_safe to ensure the hardware call runs in the main loop context
+      Bridge.provide_safe("set_led_state", set_led_state);
+    }
+
+    void loop() {
+    }
+
+    void set_led_state(bool state) {
+      digitalWrite(LED_BUILTIN, state ? LOW : HIGH);
+    }
+    ```
+2. **Install the Python Dependency** 
+   
+    Install the msgpack library using the system package manager:
+
+    ```bash
+    sudo apt install python3-msgpack
+    ```
+3. **Create the Python Script** 
+   
+   Create a new file named msgpack_test.py:
+
+    ```bash
+    nano msgpack_test.py
+    ```
+4. **Add the Script Content**
+  
+   Copy and paste the following code. This script connects manually to the Router's Unix socket and sends a raw RPC request.
+  
+    ```python
+    import socket
+    import msgpack
+    import sys
+
+    # 1. Define the connection to the Router's Unix Socket
+    SOCKET_PATH = "/var/run/arduino-router.sock"
+
+    # 2. Parse command line arguments
+    # Default to turning LED ON (True) if no argument is provided
+    led_state = True 
+
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if arg == "1":
+            led_state = True
+        elif arg == "0":
+            led_state = False
+        else:
+            print("Usage: python3 msgpack_test.py [1|0]")
+            sys.exit(1)
+
+    print(f"Sending request to set LED: {led_state}")
+
+    # 3. Create the MessagePack RPC Request
+    # Format: [type=0 (Request), msgid=1, method="set_led_state", params=[led_state]]
+    request = [0, 1, "set_led_state", [led_state]]
+    packed_req = msgpack.packb(request)
+
+    # 4. Send the request
+    try:
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as client:
+            client.connect(SOCKET_PATH)
+            client.sendall(packed_req)
+            
+            # 5. Receive the response
+            response_data = client.recv(1024)
+            response = msgpack.unpackb(response_data)
+            
+            # Response Format: [type=1 (Response), msgid=1, error=None, result=None]
+            print(f"Router Response: {response}")
+            
+    except Exception as e:
+        print(f"Connection failed: {e}")
+    ```
+
+**Running the Example**
+
+You can now test the connection by running the script from the terminal and passing `1` (ON) or `0` (OFF):
+
+```bash
+python3 msgpack_test.py 1 # to turn on the LED
+# or
+python3 msgpack_test.py 0 # to turn off the LED
+```
+![Custom Python to Router example](assets/custom-python-rpc.png)
+
+
 ### SPI
 
 The UNO Q supports SPI communication, which allows data transmission between the board and other SPI-compatible devices.