docs: add Troubleshooting and Safety & Emergency Stop sections to README #39
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: CI | |
| on: | |
| push: | |
| branches: [hugging-face-reachy-mini-tier-1] | |
| pull_request: | |
| branches: [hugging-face-reachy-mini-tier-1, main] | |
| jobs: | |
| # ─── Go Tunnel: build + unit tests ─────────────────────────────────────────── | |
| tunnel: | |
| name: Go Tunnel (build + test) | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-go@v5 | |
| with: | |
| go-version: "1.25" | |
| cache: true | |
| - name: Build tunnel binary | |
| run: make build | |
| - name: Run Go tests | |
| run: make test | |
| - name: Upload tunnel binary | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: tunnel-bin | |
| path: | | |
| bin/ | |
| .zenoh-c/lib/ | |
| retention-days: 1 | |
| # ─── Python Bridge: lint + sim unit tests ──────────────────────────────────── | |
| bridge-sim: | |
| name: Reachy Mini Bridge (MuJoCo sim) | |
| runs-on: ubuntu-latest | |
| needs: tunnel | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.10" | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install mujoco==3.10.0 numpy==2.2.6 eclipse-zenoh==1.9.0 x402==2.16.0 eth-account==0.13.7 httpx==0.28.1 web3==7.16.0 | |
| - name: Install reachy_mini package (official MJCF) | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y libcairo2-dev libgirepository1.0-dev pkg-config | |
| pip install git+https://github.com/pollen-robotics/reachy_mini.git@v1.8.4 | |
| python -c " | |
| import importlib.util, pathlib | |
| spec = importlib.util.find_spec('reachy_mini') | |
| p = pathlib.Path(spec.origin).parent / 'descriptions' / 'reachy_mini' / 'mjcf' / 'scenes' / 'minimal.xml' | |
| assert p.exists(), f'MJCF not found at {p}' | |
| print(f'MJCF OK: {p}') | |
| " | |
| - name: Download tunnel binary | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: tunnel-bin | |
| - name: Make tunnel binary executable | |
| run: | | |
| chmod +x bin/* || true | |
| echo "LD_LIBRARY_PATH=$(pwd)/.zenoh-c/lib" >> $GITHUB_ENV | |
| - name: Run sim-to-sim validation (MuJoCo only, Webots skipped) | |
| working-directory: bridge/reachy_mini/mujoco_sim_bridge/simulation | |
| run: | | |
| python -c " | |
| import sys, os | |
| # Add parent dir (mujoco_sim_bridge) so 'policy' and 'simulation' are importable | |
| sys.path.insert(0, os.path.dirname(os.getcwd())) | |
| sys.path.insert(0, '.') | |
| from environment import ReachyMiniEnvironment | |
| from policy.controller import ReachyTaskPolicy | |
| from metrics import SimulationMetricsTracker | |
| env = ReachyMiniEnvironment() | |
| policy = ReachyTaskPolicy() | |
| metrics = SimulationMetricsTracker() | |
| obs = env.reset(target_object='apple') | |
| policy.reset() | |
| metrics.reset(obs) | |
| last = {} | |
| while obs['sim_time'] < 8.0: | |
| action, phase = policy.compute_action(obs, last) | |
| env.set_control(action) | |
| obs = env.step(steps=5) | |
| last = metrics.update(obs) | |
| if last.get('task_completed', False): | |
| break | |
| s = metrics.get_summary() | |
| print(f'task_completed: {s[\"task_completed\"]}') | |
| print(f'tracking_success_rate: {s[\"tracking_success_rate\"]}') | |
| assert s['task_completed'], 'Task did not complete' | |
| assert s['tracking_success_rate'] >= 0.8, f'Success rate too low: {s[\"tracking_success_rate\"]}' | |
| print('OK - MuJoCo simulation passed') | |
| " | |
| - name: Run payment gate test | |
| continue-on-error: true | |
| working-directory: bridge/reachy_mini | |
| run: python test_payment_gate.py | |
| env: | |
| TUNNEL_BIN: ${{ github.workspace }}/bin/tunnel | |
| - name: Run E2E paid action test (deterministic, no blockchain) | |
| continue-on-error: true # Requires live Fabric Gateway connection | |
| working-directory: bridge/reachy_mini | |
| run: python test_e2e_paid_action.py | |
| env: | |
| TUNNEL_BIN: ${{ github.workspace }}/bin/tunnel | |
| WEBOTS_EXE: "" # Force skip Webots in CI | |
| # ─── Full Sim2Sim with Webots ──────────────────────────────────────────────── | |
| sim2sim-webots: | |
| name: Sim2Sim (MuJoCo + Webots) | |
| runs-on: ubuntu-latest | |
| needs: tunnel | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.10" | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install mujoco==3.10.0 numpy==2.2.6 eclipse-zenoh==1.9.0 x402==2.16.0 eth-account==0.13.7 httpx==0.28.1 web3==7.16.0 | |
| - name: Install reachy_mini package | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y libcairo2-dev libgirepository1.0-dev pkg-config | |
| pip install git+https://github.com/pollen-robotics/reachy_mini.git@v1.8.4 | |
| - name: Install Webots | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y wget xvfb \ | |
| libgl1 libglu1-mesa libglib2.0-0 libgomp1 \ | |
| libfontconfig1 libxkbcommon0 libdbus-1-3 \ | |
| libx11-6 libx11-xcb1 libxcb1 libxext6 libxrender1 libxtst6 libxi6 libxss1 \ | |
| libqt5core5a libqt5gui5 libqt5widgets5 libqt5network5 libqt5svg5 \ | |
| libqt5webengine5 libqt5webenginecore5 libqt5webenginewidgets5 \ | |
| libqt5multimedia5 libqt5printsupport5 libqt5concurrent5 \ | |
| libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \ | |
| libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 | |
| # libsndio (version varies by distro) | |
| sudo apt-get install -y libsndio7.0 2>/dev/null || sudo apt-get install -y libsndio-dev 2>/dev/null || true | |
| wget -q https://github.com/cyberbotics/webots/releases/download/R2025a/webots-R2025a-x86-64.tar.bz2 | |
| sudo tar xjf webots-R2025a-x86-64.tar.bz2 -C /usr/local | |
| rm webots-R2025a-x86-64.tar.bz2 | |
| - name: Download tunnel binary | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: tunnel-bin | |
| path: bin/ | |
| - name: Run full sim2sim (MuJoCo + Webots) | |
| working-directory: bridge/reachy_mini/mujoco_sim_bridge/simulation | |
| env: | |
| WEBOTS_EXE: /usr/local/webots/webots | |
| WEBOTS_CONTROLLER_PATH: ${{ github.workspace }}/bridge/reachy_mini/mujoco_sim_bridge/simulation/scenes/controllers | |
| REACHY_SIM2SIM_BATCH: "1" | |
| QT_QPA_PLATFORM: offscreen | |
| LD_LIBRARY_PATH: /usr/local/webots/lib | |
| run: | | |
| xvfb-run -a -s "-screen 0 1280x1024x24" python -c " | |
| import sys, os | |
| sys.path.insert(0, os.path.dirname(os.getcwd())) | |
| sys.path.insert(0, '.') | |
| from sim2sim import Sim2SimValidator | |
| from environment import ReachyMiniEnvironment | |
| from metrics import SimulationMetricsTracker | |
| from policy.controller import ReachyTaskPolicy | |
| v = Sim2SimValidator(ReachyMiniEnvironment, ReachyTaskPolicy, SimulationMetricsTracker) | |
| r = v.run_validation() | |
| score = r['overall_sim2sim_robustness_score'] | |
| sims = r['simulators_evaluated'] | |
| print(f'Sim2Sim score: {score}') | |
| print(f'Simulators: {sims}') | |
| assert score >= 0.9, f'Sim2Sim score too low: {score}' | |
| assert 'Webots' in sims, 'Webots not evaluated' | |
| print('OK - Full sim2sim passed (MuJoCo + Webots)') | |
| " | |
| - name: Upload Webots result | |
| if: always() | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: webots-sim2sim-result | |
| path: bridge/reachy_mini/mujoco_sim_bridge/simulation/webots_sim2sim_result.json | |
| retention-days: 90 | |
| if-no-files-found: ignore | |
| # ─── Live Base Sepolia E2E (on-chain payment) ──────────────────────────────── | |
| base-sepolia-e2e: | |
| name: Live Base Sepolia E2E (on-chain) | |
| runs-on: ubuntu-latest | |
| needs: tunnel | |
| if: github.event_name == 'push' | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-go@v5 | |
| with: | |
| go-version: "1.25" | |
| cache: true | |
| - name: Build tunnel | |
| run: make build | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: "3.10" | |
| - name: Install Python dependencies | |
| run: | | |
| python -m pip install --upgrade pip | |
| pip install mujoco==3.10.0 numpy==2.2.6 eclipse-zenoh==1.9.0 x402==2.16.0 eth-account==0.13.7 httpx==0.28.1 web3==7.16.0 | |
| - name: Install reachy_mini | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y libcairo2-dev libgirepository1.0-dev pkg-config | |
| pip install git+https://github.com/pollen-robotics/reachy_mini.git@v1.8.4 | |
| - name: Install Webots | |
| run: | | |
| sudo apt-get install -y wget xvfb libgl1 libglu1-mesa libglib2.0-0 libgomp1 \ | |
| libfontconfig1 libxkbcommon0 libdbus-1-3 libx11-6 libx11-xcb1 \ | |
| libxcb1 libxext6 libxrender1 libxtst6 libxi6 libxss1 \ | |
| libqt5core5a libqt5gui5 libqt5widgets5 libqt5network5 libqt5svg5 \ | |
| libqt5webengine5 libqt5webenginecore5 libqt5webenginewidgets5 \ | |
| libqt5multimedia5 libqt5printsupport5 libqt5concurrent5 \ | |
| libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-randr0 \ | |
| libxcb-render-util0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0 | |
| sudo apt-get install -y libsndio7.0 2>/dev/null || sudo apt-get install -y libsndio-dev 2>/dev/null || true | |
| wget -q https://github.com/cyberbotics/webots/releases/download/R2025a/webots-R2025a-x86-64.tar.bz2 | |
| sudo tar xjf webots-R2025a-x86-64.tar.bz2 -C /usr/local | |
| rm webots-R2025a-x86-64.tar.bz2 | |
| - name: Run Base Sepolia E2E | |
| working-directory: bridge/reachy_mini | |
| run: xvfb-run -a -s "-screen 0 1280x1024x24" python test_base_sepolia_tunnel_e2e.py | |
| env: | |
| PRIVATE_KEY: ${{ secrets.BASE_SEPOLIA_PRIVATE_KEY }} | |
| ROBO_PAYEE_ADDRESS: ${{ secrets.ROBO_PAYEE_ADDRESS }} | |
| ROBOT_ID: reachy-mini-kauker | |
| TUNNEL_BIN: ${{ github.workspace }}/bin/tunnel | |
| LD_LIBRARY_PATH: ${{ github.workspace }}/.zenoh-c/lib:/usr/local/webots/lib | |
| PROXY_WS_URL: wss://api.fabric.foundation/api/core/ws/robot | |
| WEBOTS_EXE: /usr/local/webots/webots | |
| WEBOTS_CONTROLLER_PATH: ${{ github.workspace }}/bridge/reachy_mini/mujoco_sim_bridge/simulation/scenes/controllers | |
| REACHY_SIM2SIM_BATCH: "1" | |
| QT_QPA_PLATFORM: offscreen | |
| - name: Upload evidence | |
| if: always() | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: base-sepolia-evidence | |
| path: bridge/reachy_mini/base_sepolia_result*.json | |
| retention-days: 90 | |
| if-no-files-found: ignore |