HANDOFF.md

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:

left_joint_1 ... left_joint_6,
left_gripper,
right_joint_1 ... right_joint_6,
right_gripper

Camera order:

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:

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:

action_type=absolute_joint_position

The robot client must not apply an additional delta-to-absolute conversion.

3. Environment installation

Install the server environment:

cd /path/to/StreamPI-PiperX-Real6
bash scripts/setup_server_env.sh

Optionally install an independent client environment:

cd /path/to/StreamPI-PiperX-Real6
bash scripts/setup_client_env.sh

An existing compatible Python interpreter may instead be selected explicitly:

export OPENPI_PYTHON=/path/to/python

4. Release verification

cd /path/to/StreamPI-PiperX-Real6

export OPENPI_PYTHON=/path/to/python
bash scripts/verify_release.sh

Expected final markers include:

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.

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:

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

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:

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:

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:

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:

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:

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.