release: bump version to 0.71.0
This commit is contained in:
linkong
@@ -244,22 +244,27 @@ The recommended direction is a small platform compatibility layer for port liste
|
||||
|
||||
The production frontend shape is `vite build` static output served by nginx/Caddy or an equivalent HTTP server. Do not use `bun run dev` or `vite preview` in production. The project does not maintain a parallel Webpack build chain; if a future enterprise requirement needs closer Webpack-ecosystem compatibility, run an Rsbuild/Rspack spike first. Electron should only be evaluated when the official target becomes an offline desktop application.
|
||||
|
||||
## Optional Motion Agent Startup
|
||||
## Default Motion Agent Startup
|
||||
|
||||
`planet.sh` can now manage the local Motion Capture Agent. It is disabled by default so ordinary development machines do not fail startup when cameras, OpenCV, or MediaPipe are unavailable.
|
||||
`planet.sh` now starts the local Motion Agent by default during `start` and full `restart`. This makes the Earth page, UE clients, and debug clients able to connect to `ws://127.0.0.1:8765/ws/gestures` immediately. If the machine has no usable camera, implicit default startup falls back to dry-run protocol mode and does not block backend/frontend startup. Explicit Motion Agent startup through `--motion-agent`, camera indexes, camera URLs, or WSL USB options still treats live camera failures as real errors.
|
||||
|
||||
Start it with:
|
||||
To skip Motion Agent for this run:
|
||||
|
||||
```bash
|
||||
./planet.sh start --motion-agent
|
||||
./planet.sh start --non-motion-agent
|
||||
./planet.sh restart --non-motion-agent
|
||||
```
|
||||
|
||||
Common options:
|
||||
|
||||
- `--motion-agent` / `-m`: start or restart the Motion Agent for this command.
|
||||
- `--non-motion-agent`: do not start Motion Agent for this `start` or full `restart`.
|
||||
- `--motion-agent` / `-m`: explicitly start or restart the Motion Agent for this command; live camera failures are reported as failures.
|
||||
- `--motion-agent-port <port>`: override the default WebSocket port `8765`.
|
||||
- `--motion-agent-mode <mode>`: choose `auto`, `single`, `dual_redundant`, `single_fallback`, or `calibrated_3d`; `dual` is kept as a compatibility alias for redundant dual-camera mode.
|
||||
- `--motion-agent-camera-indexes <indexes>`: override auto-detected camera indexes, for example `0` or `0,1`. The same can be provided through `MOTION_AGENT_CAMERA_INDEXES=0,1`.
|
||||
- `--motion-agent-camera-urls <urls>`: use RTSP/HTTP camera streams, useful for WSL, phone cameras, or network cameras. The same can be provided through `MOTION_AGENT_CAMERA_URLS=...`.
|
||||
- `--motion-agent-wsl-usbipd`: in WSL, try to attach the single detected Windows USB camera through `usbipd-win`.
|
||||
- `--motion-agent-wsl-usbipd-busid <BUSID>`: in WSL, attach the camera matching a `usbipd list` BUSID; use this when multiple cameras are present.
|
||||
- `--motion-agent-dry-run`: start only the protocol service without opening cameras or loading CV dependencies; useful for Web client debugging.
|
||||
|
||||
Non-dry-run live mode checks `mediapipe` and `opencv-python` before startup. If the current `.venv` is missing them, the script automatically runs:
|
||||
@@ -268,13 +273,17 @@ Non-dry-run live mode checks `mediapipe` and `opencv-python` before startup. If
|
||||
uv add mediapipe opencv-python
|
||||
```
|
||||
|
||||
To disable startup-time auto-install:
|
||||
To disable startup-time Python CV dependency auto-install:
|
||||
|
||||
```bash
|
||||
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
|
||||
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start
|
||||
```
|
||||
|
||||
Live mode auto-detects `/dev/video*` and passes the first two indexes to the Motion Agent. In WSL, Windows cameras usually do not appear as `/dev/video*` automatically. Check available devices first:
|
||||
`./planet.sh init` also performs a WSL host dependency preflight for `usbipd-win`. If `usbipd.exe` is missing, the script first tries `winget install -e --id dorssel.usbipd-win`, then reuses the repository-bundled dorssel.usbipd-win MSI fallback. If that cached MSI is missing or an architecture-specific MSI is needed, it downloads one and requests an Administrator PowerShell installation. This is best-effort: failure prints next steps but does not block normal initialization. Use `./planet.sh init --non-motion-agent` to skip this preflight.
|
||||
|
||||
Live mode auto-detects `/dev/video*`, then prefers an OpenCV probe to keep only indexes that can open and return frames before passing them to the Motion Agent. In WSL/USB camera setups, one camera can expose multiple `/dev/video*` nodes, and some of them are metadata or non-capture nodes; the script skips those unreadable indexes. In WSL, Windows cameras usually do not appear as `/dev/video*` automatically. Check available devices first:
|
||||
|
||||
Live capture defaults to low-latency settings: `640x360` input and roughly `15Hz` recognition events. The worker uses latest-frame reader threads and keeps only the newest frame from each camera, so a slow MediaPipe frame does not make the recognizer drain stale camera backlog. The skeleton debug stream is disabled by default and is only sent at roughly `8Hz` while the Earth motion debug panel is open, so normal gesture control is not slowed down by debug data. Status events report both capture FPS and recognition FPS to separate camera throughput issues from recognition cost.
|
||||
|
||||
```bash
|
||||
ls /dev/video*
|
||||
@@ -292,20 +301,42 @@ In WSL, the more general path is to connect a phone or network camera through an
|
||||
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
|
||||
```
|
||||
|
||||
If WSL has no `/dev/video*` and no `--motion-agent-camera-urls` is provided, live startup stops and prints guidance instead of silently falling back to dry-run. Choose one of:
|
||||
To use a Windows USB camera directly from WSL, let the script call `usbipd-win`. This is opt-in because an attached camera is usually temporarily unavailable to Windows apps while WSL owns it.
|
||||
|
||||
When there is only one camera:
|
||||
|
||||
```bash
|
||||
./planet.sh start --motion-agent --motion-agent-wsl-usbipd
|
||||
```
|
||||
|
||||
When there are multiple cameras, inspect the BUSID first and pass it explicitly:
|
||||
|
||||
```bash
|
||||
usbipd.exe list
|
||||
./planet.sh start --motion-agent --motion-agent-wsl-usbipd-busid 3-2
|
||||
```
|
||||
|
||||
If `usbipd attach` says the device is not shared or bound, the script tries to open an Administrator PowerShell to run `usbipd bind`, then retries attach. If UAC is canceled or automatic bind fails, run this manually from an Administrator PowerShell:
|
||||
|
||||
```powershell
|
||||
usbipd bind --busid 3-2
|
||||
usbipd attach --wsl --busid 3-2
|
||||
```
|
||||
|
||||
If WSL has no `/dev/video*` and no `--motion-agent-camera-urls` is provided, implicit default startup falls back to dry-run. Explicit live startup stops and prints guidance. Choose one of:
|
||||
|
||||
```bash
|
||||
./planet.sh start --motion-agent --motion-agent-camera-urls http://<phone-ip>:8080/video
|
||||
./planet.sh start --motion-agent --motion-agent-wsl-usbipd
|
||||
./planet.sh start --motion-agent --motion-agent-dry-run
|
||||
```
|
||||
|
||||
Automatic dry-run fallback only happens when `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1` is explicitly set.
|
||||
For explicit live startup, automatic dry-run fallback only happens when `PLANET_MOTION_AGENT_WSL_ALLOW_DRY_RUN_FALLBACK=1` is set.
|
||||
|
||||
Environment-variable startup is also supported:
|
||||
`--non-motion-agent` is the command-level opt-out. Environment variables can still tune how the service starts:
|
||||
|
||||
```bash
|
||||
PLANET_START_MOTION_AGENT=1 ./planet.sh start
|
||||
MOTION_AGENT_DRY_RUN=1 PLANET_START_MOTION_AGENT=1 ./planet.sh start
|
||||
MOTION_AGENT_DRY_RUN=1 ./planet.sh start
|
||||
```
|
||||
|
||||
Logs:
|
||||
|
||||
Reference in New Issue
Block a user