# Stato del progetto RealSense-D435 — 2026-05-19

## TL;DR

- ✅ Driver completo e funzionante su questo robot (Jetson Xavier NX, D435 su USB 2.1)
- ✅ RGB 640x480 + Depth 640x480 simultanei via REST/WebSocket
- ✅ Intrinsics, point cloud, measure, snapshot, recording, WebSocket stream — tutti operativi
- ⚠️ Framerate effettivo ~4 fps (limitato dalla banda USB 2.0). Su porta USB 3 il driver riprende automaticamente 640x480@30.

## Cosa è stato risolto in questa sessione

1. **Bug install di librealsense v2.55.1**: il `.so` principale di `pyrealsense2` non viene installato dal CMake — solo `pyrsutils.so`. Workaround nel `Dockerfile`: si copia il `.so` direttamente da `/src/librealsense/build/Release/` e si aggiunge un `__init__.py` che riesporta il submodule (`from .pyrealsense2 import *`).
2. **D4xx su USB 2 — formato color**: BGR8/RGB8 vanno in timeout su USB 2 anche da soli (firmware D4xx). Solo **YUYV** sostiene il transfer su USB 2. Il driver ora rileva `usb_type_descriptor` e su USB 2.x configura color = YUYV, convertendo in BGR via `cv2.cvtColor` in `capture()`.
3. **`rs.align` incompatibile con YUYV**: il blocco di processing fallisce con "Error occurred during execution of the processing block". Su USB 2 saltiamo l'alignment hardware e facciamo un resize numpy del color per matchare la shape del depth (approximate alignment, OK per use case standard).
4. **Risoluzione massima USB 2**: 640x480@15 (configurato) → ~4 fps reali. Testate tutte le combinazioni; 848x480 dà "Couldn't resolve requests" anche in YUYV.

## Hardware setup (constatato)

```
Jetson Xavier NX
├─ Bus 1 (USB 2.0, 480M)
│   ├─ Hub interno → Inspire Hands (cdc_acm /dev/ttyACM0) + ch341
│   └─ Hub esterno (collegato a porta USB-C frontale)
│       ├─ Tastiera, mouse, ax88179 (Ethernet)
│       └─ D435 ← qui
└─ Bus 2 (USB 3.0, 10000M) — VUOTO, ma probabilmente non esposto esternamente
```

- D435 serial: `933322070696`, fw `05.16.00.01`, USB `8086:0b07`, `usb_type = 2.1`
- La porta USB-C frontale del robot H1 è cablata **USB 2 hardware** (confermato indirettamente: l'ax88179 sullo stesso hub gira a 480M)
- Le Inspire Hands sono su hub interno separato — non vanno toccate

## Endpoints (verificati)

| Endpoint | HTTP | Note |
|---|---|---|
| `/api/health` | 200 | sdk_initialized=true, camera_open=true |
| `/api/status` | 200 | include `color_available`, `usb_type` |
| `/api/discover` | 200 | rileva D435 serial `933322070696` |
| `/api/rgb` | 200 | JPEG 640x480 |
| `/api/depth` | 200 | PNG 16-bit 640x480 |
| `/api/depth/color` | 200 | JPEG colormap JET 640x480 |
| `/api/capture` | 200 | JSON con tutte e tre base64 |
| `/api/intrinsics` | 200 | ir + rgb + extrinsics_ir_to_rgb |
| `/api/pointcloud`, `/api/pointcloud/roi`, `/api/measure`, `/api/snapshot` | 200 | da testare in scenario reale |

## File modificati in questa sessione

- `Dockerfile`: fix install pyrealsense2 (`.so` + `__init__.py`)
- `src/backend/services/camera.py`:
  - rileva `usb_type_descriptor` in `open()`
  - profilo USB 2 (YUYV 640x480@15 color + Z16 640x480@15 depth)
  - conversione YUYV → BGR in `capture()` via `cv2.cvtColor` (manuale, dopo aver ricostruito lo shape (H,W,2))
  - skip `rs.align` su USB 2; resize numpy del color per matchare il depth
  - nuovi metodi `is_color_available()`, `usb_type()` per diagnostica
- `src/backend/api/routes.py`: `/api/status` espone `color_available` + `usb_type`

## Da fare prossima volta

- Testare `/api/pointcloud` e `/api/measure` in un ambiente reale e verificare che l'approximate alignment (resize) sia accettabile per il caso d'uso. Se no, implementare alignment proprio con `cv2.remap` usando intrinsics + extrinsics.
- Decidere se esporre il flag `usb_type` nel frontend React per warning utente
- Eventualmente: profilo configurabile via `.env` per chi vuole controllare manualmente

## Modifiche al setup ambiente (persistono nei reboot)

1. `/etc/systemd/system/docker.service.d/http-proxy.conf` (proxy daemon)
2. `unitree` nel gruppo `docker`
3. `~/.docker/config.json` con proxy CLI + cli-plugins path
4. `~/.docker/cli-plugins/docker-compose` (plugin v2)

## Avvio rapido

```bash
cd ~/Robot_2026/RealSense-D435
sg docker -c "docker compose up -d"          # già buildato
curl -s http://localhost:8878/api/health     # check
curl -s http://localhost:8878/api/rgb -o rgb.jpg
curl -s http://localhost:8878/api/depth -o depth.png
```