add tutorials (#10)

* tutorial upload

* Update Streaming.md

* add static link

* updated tutorial and README

Author: SimoneFassio

.gitignore

@@ -24,4 +24,5 @@ build
 *.pytest_cache
 
 photos
-venv
+venv
+myenv/

README.md

@@ -1,7 +1,34 @@
 # NEW EVA 2025
+EVA is PoliTOcean main ROV ready for MATE Competition.
+
+<p align="center">
+<img src="docs/eva.png" width="60%" height="60%">
+</p>
+<p align="center">
+<img src="docs/cad.png" width="60%" height="60%">
+</p>
+
+## Overview
+The ROV’s software stack is built around three integrated components: NEXUS, Oceanix, and STM Nucleo firmware. NEXUS, running on the control station, delivers real-time video, telemetry, and control to the pilot. Oceanix, hosted on a Raspberry Pi 5, handles mission logic, sensor fusion, and dynamic thrust allocation. The STM Nucleo executes low-level motor and actuator control via lightweight firmware, offering additional GPIOs with PWM support at very low cost. These components communicate via MQTT, I²C and a custom serial protocol, ensuring modularity, low latency, and robustness.
+The decision to adopt the Raspberry Pi 5 over alternatives like the NVIDIA Jetson Nano was driven by its efficiency, lower power consumption, and cost-effectiveness. While the Jetson’s GPU acceleration benefits AI workloads, our architecture prioritizes real-time control, sensor polling and network communication (tasks where the Pi 5's CPU is more than sufficient).  Similarly, the STM Nucleo adds PWM-capable GPIOs and supports a modular architecture at minimal cost. This design allows us to upgrade sensors or control logic with minimal effort, supporting rapid development and scalability.
 <p align="center">
-<img src="docs/eva.jpg" width="60%" height="60%">
+<img src="docs/Software_SID.png" width="60%" height="60%">
 </p>
 
-## Components
-The firmware for a specific component can be find in [this](firmware/) directory...
+
+## NEXUS
+NEXUS is implemented as a Flask‑based Python application that delivers a desktop‑style web interface to the ROV pilot. Within the browser window, operators see five live feeds from the Raspberry Pi 5. This year, we upgraded the streaming system to WebRTC, enabling GPU-accelerated rendering of the video directly in the browser. This allowed us to reduce latency by up to 200 ms and add real-time lens distortion correction for improved camera visualization, while fully leveraging the onboard H.264 encoding of the two front cameras. Alongside the video panels, dynamic charts visualize the ROV’s attitude (roll, pitch, yaw) and depth readings from the Bar02 sensor. Float functions are accessed through a dedicated section. Commands, from joystick movements to arm actuation, are serialized as JSON and sent over MQTT to Oceanix. 
+
+## Oceanix
+Oceanix is our C++ application running on the Raspberry Pi 5, structured in an object‑oriented paradigm to isolate sensors, controllers and communication services. The Pi hosts a Mosquitto MQTT broker that relays messages between NEXUS, the debug tool and Oceanix itself. Joystick inputs arrive on the command topic, the resulting force and moment vectors feed a thrust allocation algorithm that computes individual PWM setpoints for eight thrusters.
+These setpoints are forwarded over a high‑speed UART link to the STM Nucleo board. Simultaneously, Oceanix polls the onboard IMU and Bar02 sensor at 200 Hz via I²C, combining accelerometer, gyroscope and pressure data in a complementary filter to estimate depth and attitude.
+
+## STM Nucleo
+On the NUCLEO‑L432KC board, a bare‑metal C application built on ST’s HAL libraries listens on UART for a continuous stream of PWM duty‑cycle values and servo positions sent by Oceanix at 100 Hz. Each packet includes a CRC to verify integrity; in the event of a CRC failure, the firmware retains the previous command until valid data resumes. Hardware timers generate PWM signals with 1 µs resolution, which drive optocouplers feeding our motor driver MOSFETs. For arm control, a specially designed packet is received to regulate the actuator and driver, including their speed and direction. The firmware’s emphasis on deterministic timing and minimal interrupt jitter guarantees that high‑frequency control loops run reliably, enabling both precise thrust control and smooth manipulator operation.
+
+## Helper
+For deeper analysis and tuning, we maintain a companion Python/Tk debug tool that connects via MQTT to display raw sensor dumps, per‑motor thrust values, live logs and adjustable control‑loop parameters such as controller gains. This app is divided into windows, is very good for lab testing since all essentials commands can be send to Oceanix, also statuses are printed along with real time plot for controller tuning, camera streamning can be tested and snapshot can be taken, also the configuration page edits the config.json on the Raspberry Pi.
+
+# Usage
+in rasp_setup all tutorial for setting up a new raspberry are contained, focusing on the handling of the camera also in general .
+usage.md contains instructions for EVA.

docs/Usage.md Usage.mddocs/Usage.md renamed to Usage.md

@@ -0,0 +1,121 @@
+## 🎯 **Goal**
+
+Instead of dealing with changing `/dev/video4`, `/dev/video6`, etc., we want:
+
+```bash
+/dev/camera-bottom
+/dev/camera-top
+/dev/camera-main
+/dev/camera-right
+/dev/camera-arm
+```
+
+that always point to the correct camera, based on which USB port it’s plugged into.
+
+---
+
+## 🧰 Prerequisites
+
+Make sure you have:
+
+* `v4l-utils` installed (for `v4l2-ctl`)
+* root access (`sudo`)
+
+If not already installed:
+
+```bash
+sudo apt update
+sudo apt install v4l-utils
+```
+
+---
+
+## 📝 Step 1: List Video Devices
+
+List your connected cameras and the video devices they expose:
+
+```bash
+v4l2-ctl --list-devices
+```
+
+You'll see output like:
+
+```
+HD USB CAMERA: HD USB CAMERA (usb-xhci-hcd.0-2.2):
+    /dev/video4
+    /dev/video5
+
+exploreHD USB Camera: exploreHD (usb-xhci-hcd.0-2.4):
+    /dev/video8
+    /dev/video9
+```
+
+exploreHD USB Cameras are managed by DWE OS that already uses static path, so ignore these cameras in this tutorial
+
+---
+
+## 🔍 Step 2: Find the `ID_PATH` for the Correct Device
+
+Pick the device that corresponds to the **stream you want to use** (e.g. `/dev/video4`), then run:
+
+```bash
+udevadm info /dev/video4 | grep ID_PATH
+```
+
+You'll get something like:
+
+```
+E: ID_PATH=platform-xhci-hcd.0-usb-0:2.2:1.0
+```
+
+Write that down — that's the stable ID of that USB port.
+
+Repeat this for all cameras you want to assign.
+
+---
+
+## 🧩 Step 3: Create a udev Rule File
+
+Create a new udev rules file:
+
+```bash
+sudo nano /etc/udev/rules.d/99-usb-cameras.rules
+```
+
+Add one line per camera, like this:
+
+```udev
+# Bottom camera
+SUBSYSTEM=="video4linux", ENV{ID_PATH}=="platform-xhci-hcd.0-usb-0:2.2:1.0", ATTR{index}=="0", SYMLINK+="camera-bottom"
+
+# Top camera
+SUBSYSTEM=="video4linux", ENV{ID_PATH}=="platform-xhci-hcd.0-usb-0:2.3:1.0", ATTR{index}=="0", SYMLINK+="camera-top"
+```
+
+📌 **Make sure you adjust the `ID_PATH` values** to the correct ones from your own system.
+the ATTR{index}=="0" is to make sure we are selecting the right interface of the camera, for the DWE camera the index is 2 to use H.264
+
+---
+
+## 🔄 Step 4: Reload udev and Trigger
+
+```bash
+sudo udevadm control --reload-rules
+sudo udevadm trigger
+```
+
+Then check:
+
+```bash
+ls -l /dev/camera-*
+```
+
+You should see:
+
+```
+/dev/camera-bottom -> video4
+/dev/camera-top -> video6
+...
+```
+
+🎉 Done!

docs/Software_SID.png

@@ -0,0 +1,45 @@
+# Linux Camera Systems
+
+Cameras in Linux are seen as `/dev/video*`. They have different output formats and resolutions. To check the available formats, use the following command:
+
+```bash
+v4l2-ctl -d /dev/video0 --list-formats-ext
+```
+
+after the camera static link setup is best to use:
+
+```bash
+v4l2-ctl -d /dev/camera-main --list-formats-ext
+```
+also to check that the ATTR{index} is set up correctly.
+
+## Camera Formats Explained
+
+The formats can be MJPG or H264:
+
+- **MJPG (Motion JPEG)**: A series of JPEG images sent in sequence. 
+  - Pros: Higher quality, widely supported
+  - Cons: Higher bandwidth usage, must be transcoded for efficient streaming
+  - Must be encoded to H264 for efficient network streaming
+  - May introduce lag on the client side due to decoding overhead
+  - To stream in MJPG use ustreamer, easy to set up and easy to work with, also with the snapshots
+
+- **H264**: A compressed video format
+  - Pros: Already compressed, lower bandwidth, ready for Real-Time Communication (RTC)
+  - Cons: May have slightly lower quality than MJPG at the same bitrate
+  - DWE cameras can output compressed H264 natively and are streamed directly with DWE OS 2
+
+## Camera Identification
+
+To understand which camera is associated with a specific `/dev/video*`, use the following command:
+
+```bash
+v4l2-ctl --list-devices
+```
+
+This script will list all video devices and their corresponding camera models/types.
+
+
+## Port Configuration and Janus Integration
+
+Both DWE_OS_2 and GStreamer streams should target `127.0.0.1` (localhost), which is where Janus is running. The port selected for each camera stream must match the corresponding port defined in the Janus streaming configuration file (`janus.plugin.streaming.cfg`). In NEXUS, the different camera streams are then identified and displayed using their respective IDs configured in Janus.

docs/cad.png

@@ -0,0 +1,92 @@
+To install Oceanix:
+
+1.  Clone the Oceanix repository:
+    ```bash
+    git clone https://github.com/PoliTOcean/Oceanix.git
+    cd Oceanix
+    ```
+
+2.  Source the install script:
+    ```bash
+    source install.sh
+    ```
+
+3. To use I2C, enable it:
+
+   *   Open the Raspberry Pi configuration:
+        ```bash
+        sudo raspi-config
+        ```
+   *   Navigate to `Interface Options` -> `I2C` -> `<Yes>` to enable it.
+   *   Reboot the Raspberry Pi for the changes to take effect:
+        ```bash
+        sudo reboot
+        ```
+
+4.  Automatic Execution with Systemd
+
+To automatically start Oceanix as a service on boot, you can use systemd.
+
+*   Create the `oceanix.service` file in `/etc/systemd/system/`:
+
+    ```bash
+    sudo nano /etc/systemd/system/oceanix.service
+    ```
+
+*   Add the following content to the `oceanix.service` file:
+
+    ```
+    [Unit]
+    Description=Oceanix Service
+    After=network.target
+
+    [Service]
+    ExecStart=/usr/bin/chrt -f 99 /home/politocean/firmware/Oceanix/build/Oceanix
+    WorkingDirectory=/home/politocean/firmware/Oceanix/build
+    Restart=always
+    User=root
+    Environment=DISPLAY=:0
+    CPUSchedulingPolicy=fifo
+    CPUSchedulingPriority=99
+
+    [Install]
+    WantedBy=multi-user.target
+    ```
+
+*   **Important:** Verify that the `ExecStart` and `WorkingDirectory` paths are correct for your Oceanix installation.  The `User` should be the user that owns the Oceanix installation.
+
+*   Enable the Oceanix service:
+
+    ```bash
+    sudo systemctl enable oceanix.service
+    ```
+
+*   restart the Oceanix service:
+
+    ```bash
+    sudo systemctl restart oceanix.service
+    ```
+
+*   Start the Oceanix service:
+
+    ```bash
+    sudo systemctl start oceanix.service
+    ```
+
+*   Check the status of the Oceanix service:
+
+    ```bash
+    sudo systemctl status oceanix.service
+    ```
+
+*   To stop the Oceanix service:
+
+    ```bash
+    sudo systemctl stop oceanix.service
+    ```
+
+*   To disable the Oceanix service:
+
+    ```bash
+    sudo systemctl disable oceanix.service
+    ```