| > **30k candidate:** default checkpoint is |
| > `checkpoints/29999`. L40 and physical-robot acceptance |
| > are still pending. Do not publish or treat as frozen. |
|
|
| # StreamPI Piper-X Real6 Deployment Handoff |
|
|
| ## 1. Release identity |
|
|
| | Item | Value | |
| |---|---| |
| | Release | `StreamPI-PiperX-Real6` | |
| | Configuration | `pi05_stream3_piper_x_real_6tasks` | |
| | Checkpoint | `checkpoints/20000` | |
| | Dataset asset | `real_piper_x_6tasks` | |
| | Model | StreamPI based on π0.5 | |
| | History horizon | 3 observations | |
| | History interval | 5 dataset frames | |
| | Prediction horizon | 10 actions | |
| | Execution length | 5 actions per inference | |
| | State dimension | 14 | |
| | Action dimension | 14 | |
|
|
| State and action order: |
|
|
| ```text |
| left_joint_1 ... left_joint_6, |
| left_gripper, |
| right_joint_1 ... right_joint_6, |
| right_gripper |
| ``` |
|
|
| Camera order: |
|
|
| ```text |
| cam_high |
| cam_left_wrist |
| cam_right_wrist |
| ``` |
|
|
| ## 2. Action semantics |
|
|
| Training uses delta actions for the 12 arm joints. |
|
|
| The 14-dimensional action layout is: |
|
|
| ```text |
| 6 left-arm joints, |
| 1 left gripper, |
| 6 right-arm joints, |
| 1 right gripper |
| ``` |
|
|
| The arm-joint dimensions use delta-action training semantics. The two gripper |
| dimensions remain absolute gripper commands. |
|
|
| During inference, `AbsoluteActions` converts the arm-joint predictions back to |
| absolute joint positions. The policy server therefore returns: |
|
|
| ```ini |
| action_type=absolute_joint_position |
| ``` |
|
|
| The robot client must not apply an additional delta-to-absolute conversion. |
|
|
| ## 3. Environment installation |
|
|
| Install the server environment: |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| bash scripts/setup_server_env.sh |
| ``` |
|
|
| Optionally install an independent client environment: |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| bash scripts/setup_client_env.sh |
| ``` |
|
|
| An existing compatible Python interpreter may instead be selected explicitly: |
|
|
| ```bash |
| export OPENPI_PYTHON=/path/to/python |
| ``` |
|
|
| ## 4. Release verification |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| |
| export OPENPI_PYTHON=/path/to/python |
| bash scripts/verify_release.sh |
| ``` |
|
|
| Expected final markers include: |
|
|
| ```text |
| CHECKPOINT_STRUCTURE_OK |
| CONFIG_REGISTRATION_OK |
| DELTA_TO_ABSOLUTE_TRANSFORM_OK |
| SERVER_CLIENT_PROTOCOL_OK |
| RELEASE_VERIFY_OK |
| ``` |
|
|
| ## 5. Synthetic loopback test |
|
|
| The loopback test starts a local policy server and sends synthetic camera |
| images and robot states. It does not connect to robot hardware. |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| |
| export OPENPI_PYTHON=/path/to/python |
| export LOOPBACK_GPU=0 |
| export LOOPBACK_PORT=18080 |
| export LOOPBACK_MAX_LATENCY_SECONDS=2.0 |
| |
| bash scripts/test_loopback.sh |
| ``` |
|
|
| Expected markers: |
|
|
| ```text |
| POLICY_WARMUP_OK |
| SMOKE_CLIENT_OK |
| LOOPBACK_TEST_OK |
| ``` |
|
|
| The script should stop its policy-server subprocess automatically when it |
| exits. |
|
|
| ## 6. Start the deployment server |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| |
| export OPENPI_PYTHON=/path/to/python |
| export POLICY_GPU=0 |
| export POLICY_HOST=0.0.0.0 |
| export POLICY_PORT=8000 |
| |
| bash scripts/start_policy_server.sh |
| ``` |
|
|
| WebSocket endpoint: |
|
|
| ```text |
| ws://SERVER_IP:8000 |
| ``` |
|
|
| Only one robot/policy session should use each server process. |
|
|
| ## 7. Warm-up before connecting hardware |
|
|
| The first inference calls for history lengths 1, 2 and 3 may trigger separate |
| JAX compilation. Complete all warm-up requests before enabling robot torque. |
|
|
| With the policy server already running: |
|
|
| ```bash |
| cd /path/to/StreamPI-PiperX-Real6 |
| |
| export OPENPI_PYTHON=/path/to/python |
| export POLICY_HOST=127.0.0.1 |
| export POLICY_PORT=8000 |
| export WARMUP_STEPS=3 |
| |
| bash scripts/warmup_policy.sh |
| ``` |
|
|
| The warm-up client uses synthetic inputs and does not access robot hardware. |
|
|
| ## 8. Client integration |
|
|
| Reference adapter: |
|
|
| ```text |
| deployment/piperx_client.py |
| ``` |
|
|
| The robot-side integration must: |
|
|
| 1. Supply all three camera observations using the documented names. |
| 2. Supply a 14-dimensional measured state in the documented order. |
| 3. Execute only the returned `execute_actions`, normally 5 actions. |
| 4. Feed the latest measured robot state into the next policy request. |
| 5. Call `reset_episode()` before every new episode. |
| 6. Keep one WebSocket connection for one robot episode. |
| 7. Never reuse observation history from the preceding episode. |
|
|
| Do not execute all 10 predicted actions and then make the next request as |
| though only 5 actions had been executed. The training and deployment contract |
| is predict 10, execute 5, and then replan. |
|
|
| ## 9. Required robot-side safety |
|
|
| The policy server does not implement complete hardware safety. The robot |
| controller must independently enforce: |
|
|
| - joint-position limits; |
| - joint-velocity and joint-acceleration limits; |
| - command timeout and watchdog; |
| - communication-loss handling; |
| - collision and workspace limits; |
| - emergency stop; |
| - torque-disable recovery; |
| - gripper-command bounds; |
| - gripper-command rate limiting. |
|
|
| The synthetic loopback observed small arm-joint chunk-boundary gaps but larger |
| gripper-command changes. Gripper limiting must remain enabled during both |
| dry-run and real-robot evaluation. |
|
|
| ## 10. Known non-fatal logs |
|
|
| On an NVIDIA machine, JAX may print unsuccessful backend probes such as: |
|
|
| ```text |
| Unable to initialize backend 'rocm' |
| Unable to initialize backend 'tpu' |
| ``` |
|
|
| These messages do not indicate CUDA inference failure. |
|
|
| Orbax may also report that it cannot read the optional |
| `EXPERIMENTAL_ORBAX_USE_DISTRIBUTED_PROCESS_ID` flag. The checkpoint is |
| considered valid when restoration completes and the verifier produces: |
|
|
| ```text |
| RELEASE_VERIFY_OK |
| ``` |
|
|
| ## 11. Acceptance scope |
|
|
| Completed: |
|
|
| - checkpoint structure verification; |
| - configuration registration verification; |
| - delta-to-absolute action-semantics verification; |
| - WebSocket server/client protocol verification; |
| - three-frame streaming-history verification; |
| - episode-reset verification; |
| - warmed L40S synthetic-loopback verification. |
|
|
| Pending: |
|
|
| - zero-torque robot communication test; |
| - low-speed dry-run; |
| - per-task real-robot success-rate evaluation; |
| - final robot safety acceptance. |
|
|
