Refactor BallBalance demo scripts and update YARP manager applications

.env

@@ -1,8 +1,11 @@
 DISPLAY=:1
 HOST_DATA_PATH=/home/bmaacaron-iit.local/Documents/Datasets/2026_PRIMI/
 
+# Default base image avoids anonymous Docker Hub pull-rate limits.
+BASE_IMAGE=public.ecr.aws/ubuntu/ubuntu:22.04
+
 # These defaults track the latest upstream refs validated in this repo.
 YCM_VERSION=v0.18.4
 YARP_VERSION=v3.12.2
 ED_VERSION=main
-ED_COMMIT=bf0a4d71c1013d2bbdf911d0ba88678ce3909ae8
+ED_COMMIT=45bce288ba616b2f19152ee96cecbb4da1c924cf

.env.example

@@ -8,4 +8,10 @@ BASE_IMAGE=public.ecr.aws/ubuntu/ubuntu:22.04
 YCM_VERSION=v0.18.4
 YARP_VERSION=v3.12.2
 ED_VERSION=main
-ED_COMMIT=bf0a4d71c1013d2bbdf911d0ba88678ce3909ae8
+ED_COMMIT=45bce288ba616b2f19152ee96cecbb4da1c924cf
+
+# Default builds omit Metavision SDK because the current SDK 5.x packages
+# require authenticated access to Prophesee's JFrog server.
+INSTALL_METAVISION_SDK=0
+PROPHESEE_JFROG_USER=
+PROPHESEE_JFROG_TOKEN=

DEVELOPER_README.md

@@ -17,7 +17,7 @@ The policy is:
 
 - redundancy in access methods is acceptable
 - hidden implementation layers should not be duplicated unnecessarily
-- `yarpmanager` applications should launch the applications themselves, not `bash` wrappers
+- `yarpmanager` applications should launch the applications themselves unless a shared script carries essential coordination behavior
 - deprecated launch wrappers should be removed when they stop carrying their own behavior
 
 ## Current Architecture
@@ -42,8 +42,8 @@ The policy is:
 There are two real launch engines now:
 
 1. `yarpmanager` XML apps
-   - generic tools and BallBalance demos launch the applications directly
-   - the BallBalance manager apps use native dependencies and connections
+   - generic tools launch the applications directly
+   - the BallBalance manager entry reuses the shared coordinated launcher so it behaves the same way as the menu and CLI
 
 2. script-based internal launchers
    - [launch-ballbalance-demo.sh](scripts/internal/launch-ballbalance-demo.sh)
@@ -87,6 +87,9 @@ The most important values are:
 - `YARP_VERSION`
 - `ED_VERSION`
 - `ED_COMMIT`
+- `INSTALL_METAVISION_SDK`
+- `PROPHESEE_JFROG_USER`
+- `PROPHESEE_JFROG_TOKEN`
 
 ### `BASE_IMAGE`
 
@@ -107,9 +110,50 @@ This keeps Ubuntu 22.04 compatibility while avoiding anonymous Docker Hub pull-r
 
 Update both together when you intentionally refresh to a newer upstream snapshot.
 
-### `vFramer` Defaults
+### `INSTALL_METAVISION_SDK`
 
-There are intentionally three configuration points now, because there are still two real launch engines and two event streams:
+The image now omits Metavision SDK by default.
+
+This is deliberate:
+
+- the BallBalance and generic GUI workflows in this repository use recorded YARP streams and do not need the SDK
+- the older anonymous `apt.prophesee.ai` feed used by upstream historical Dockerfiles is no longer the current documented Prophesee install path
+- the current SDK 5.x package flow requires authenticated JFrog access
+
+If a maintainer or user needs the SDK for live Prophesee camera integration, including upstream tools such as `atis3-bridge`, they can opt in by setting:
+
+- `INSTALL_METAVISION_SDK=1`
+- `PROPHESEE_JFROG_USER=<their Prophesee JFrog login>`
+- `PROPHESEE_JFROG_TOKEN=<their Prophesee JFrog identity token>`
+
+and then rebuilding with:
+
+```bash
+./scripts/build.sh
+```
+
+The Dockerfile follows the current documented JFrog-based install flow only when this opt-in is enabled.
+
+Reference:
+
+- Prophesee Linux SDK installation guide: https://docs.prophesee.ai/stable/installation/linux.html
+
+### Script Defaults
+
+The script launchers read [defaults.env](yarpmanager/defaults.env).
+
+That file now carries:
+
+- `BALLBALANCE_DEMO_TRIAL`
+- `VFRAMER_DEFAULT_SIDE`
+- `VFRAMER_LEFT_SRC`
+- `VFRAMER_RIGHT_SRC`
+- `VFRAMER_LEFT_NAME`
+- `VFRAMER_RIGHT_NAME`
+- `VFRAMER_WIDTH`
+- `VFRAMER_HEIGHT`
+
+There are still three `vFramer` configuration points, because there are still two real launch engines and two event streams:
 
 - `yarpmanager` `VFramer Left` app: [04-vframer-left.xml](yarpmanager/applications/04-vframer-left.xml)
 - `yarpmanager` `VFramer Right` app: [04-vframer-right.xml](yarpmanager/applications/04-vframer-right.xml)
@@ -126,6 +170,8 @@ The shared `vFramer` defaults now cover:
 - width
 - height
 
+The BallBalance demo scripts also read `BALLBALANCE_DEMO_TRIAL` from the same file, so switching between `trial_0`, `trial_1`, and `trial_2` is a one-line change.
+
 ## Developer Workflows
 
 Build:
@@ -175,18 +221,26 @@ The generic `yarpmanager` applications are direct-launch only:
 
 ### BallBalance
 
-BallBalance is intentionally available via two approaches:
+BallBalance is intentionally available through the menu, the direct CLI entrypoint, and `yarpmanager`, but those now share one implementation path.
+
+The public entrypoint is:
+
+```bash
+./scripts/demo-ballbalance.sh
+```
 
-- script-based demos from the public CLI wrappers
-- direct-launch `yarpmanager` demos
+and the manager exposes one `BallBalance Demo` application that runs the same internal coordinator.
 
-Those duplicate some session metadata, but the duplication is currently justified because the script path still carries behavior that the manager path does not:
+This shared path is intentional because the BallBalance launcher carries behavior that is worth centralizing:
 
 - pre-cleanup of matching old GUI/demo tools
 - explicit waits for ports
 - retry logic for connections
+- RGB-port fallback between `/yarpdataplayer/grabber` and `/yarpdataplayer/rgb`
+- trial selection from `BALLBALANCE_DEMO_TRIAL`
+- omission of the RGB replay stream when the selected trial has an empty `rgb/data.log`, because that input currently makes `yarpdataplayer` crash
 
-If this behavior ever gets unified elsewhere, that duplicated session metadata should be reduced.
+The older multi-demo split was removed because the mounted dataset now uses the current trial-based layout, and the supported BallBalance entry is a single demo launcher with a configurable trial.
 
 ## GitHub Distribution
 
@@ -471,7 +525,7 @@ Official GitHub references for the GHCR workflow:
 
 ## Known Limits
 
-- the current image still assumes the Prophesee / Metavision SDK path from the upstream `event-driven` Dockerfile
+- the default image omits Metavision SDK, so Prophesee-specific live camera integration is not available unless a user opts in with valid JFrog credentials
 - the exact live camera vendor is still a hardware-specific unknown
 - scripted BallBalance demos intentionally pre-clean matching GUI/demo tools before launch
 - manager-launched BallBalance demos do not pre-clean matching GUI/demo tools before launch

Dockerfile

@@ -7,8 +7,12 @@
 ARG BASE_IMAGE
 ARG YCM_VERSION=v0.18.4
 ARG YARP_VERSION=v3.12.2
+ARG ICUB_MAIN_VERSION=v2.9.0
 ARG ED_VERSION=main
-ARG ED_COMMIT=bf0a4d71c1013d2bbdf911d0ba88678ce3909ae8
+ARG ED_COMMIT=45bce288ba616b2f19152ee96cecbb4da1c924cf
+ARG INSTALL_METAVISION_SDK=0
+ARG PROPHESEE_JFROG_USER=
+ARG PROPHESEE_JFROG_TOKEN=
 
 RUN apt-get update && apt-get install -y \
     ca-certificates \
@@ -25,6 +29,7 @@
     libglew-dev \
     libglfw3-dev \
     libglm-dev \
+    libgsl-dev \
     libgraphviz-dev \
     libgstreamer-plugins-base1.0-dev \
     libgstreamer1.0-dev \
@@ -51,11 +56,25 @@
     gosu \
     && rm -rf /var/lib/apt/lists/*
 
-# The upstream event-driven Dockerfile uses Prophesee's Ubuntu 22.04 SDK feed.
-RUN echo "deb [arch=amd64 trusted=yes] https://apt.prophesee.ai/dists/public/baiTh5si/ubuntu jammy sdk" >> /etc/apt/sources.list \
-    && apt-get update \
-    && apt-get install -y metavision-sdk \
-    && rm -rf /var/lib/apt/lists/*
+# Metavision SDK is optional. The default image omits it because the current
+# Prophesee SDK 5.x install flow requires authenticated access to JFrog.
+RUN if [ "${INSTALL_METAVISION_SDK}" = "1" ]; then \
+        if [ -z "${PROPHESEE_JFROG_USER}" ] || [ -z "${PROPHESEE_JFROG_TOKEN}" ]; then \
+            echo "INSTALL_METAVISION_SDK=1 requires PROPHESEE_JFROG_USER and PROPHESEE_JFROG_TOKEN" >&2; \
+            exit 1; \
+        fi; \
+        apt-get update; \
+        apt-get install -y curl; \
+        curl -L https://propheseeai.jfrog.io/artifactory/api/security/keypair/prophesee-gpg/public >/tmp/propheseeai.jfrog.op.asc; \
+        cp /tmp/propheseeai.jfrog.op.asc /etc/apt/trusted.gpg.d/propheseeai.jfrog.op.asc; \
+        printf 'machine propheseeai.jfrog.io\nlogin %s\npassword %s\n' "${PROPHESEE_JFROG_USER}" "${PROPHESEE_JFROG_TOKEN}" >/etc/apt/auth.conf.d/prophesee-jfrog.conf; \
+        chmod 600 /etc/apt/auth.conf.d/prophesee-jfrog.conf; \
+        printf 'deb https://propheseeai.jfrog.io/artifactory/metavision-sdk-5-debian/ /\n' >/etc/apt/sources.list.d/metavision-sdk.list; \
+        apt-get update; \
+        apt-get install -y metavision-sdk; \
+        rm -f /etc/apt/auth.conf.d/prophesee-jfrog.conf /etc/apt/sources.list.d/metavision-sdk.list /tmp/propheseeai.jfrog.op.asc; \
+        rm -rf /var/lib/apt/lists/*; \
+    fi
 
 RUN git clone --depth 1 --branch "${YCM_VERSION}" https://github.com/robotology/ycm-cmake-modules.git "${CODE_DIR}/ycm" \
     && cmake -S "${CODE_DIR}/ycm" -B "${CODE_DIR}/ycm/build" \
@@ -68,6 +87,11 @@
     && cmake --install "${CODE_DIR}/yarp/build" \
     && yarp check
 
+RUN git clone --depth 1 --branch "${ICUB_MAIN_VERSION}" https://github.com/robotology/icub-main.git "${CODE_DIR}/icub-main" \
+    && cmake -S "${CODE_DIR}/icub-main" -B "${CODE_DIR}/icub-main/build" -DBUILD_TESTING=OFF \
+    && cmake --build "${CODE_DIR}/icub-main/build" -j"$(nproc)" \
+    && cmake --install "${CODE_DIR}/icub-main/build"
+
 RUN git clone --depth 1 --branch "${ED_VERSION}" https://github.com/robotology/event-driven.git "${CODE_DIR}/event-driven" \
     && test "$(git -C "${CODE_DIR}/event-driven" rev-parse HEAD)" = "${ED_COMMIT}" \
     && cmake -S "${CODE_DIR}/event-driven" -B "${CODE_DIR}/event-driven/build" \