Common program changes

Start from the Customize your first expert trajectory and keep the built-in Franka deployment. Unless stated otherwise, edit your local program.yaml and use the complete no-save command in Quickstart step 3. The complete starting files are two_moves.yaml and two_moves_checked.yaml. Keep program_id matched to the integration and use its semantic entity names.

Change repetition count or execution order

Need: make two moves instead of three, or visit B before A.

Edit: program.count and targets.drop_pose.values in program.yaml. A repeat count is the number of times its whole body runs, not the number of individual calls. With one Pick and one Place, count 2 produces four segments. Swap entire pose entries, including their orientations. If using acceptance checks, swap rest_pose.values in the same way. Update the root instruction.

The two-move program is the complete worked example. Reordering body.items changes actual execution order; preserve physical prerequisites such as picking before placing. Cyclic targets are selected by the nearest enclosing repeat iteration, not by a global call counter.

Verify: rerun with seed 7 and one environment. Check four segment entries, B → A, and the corresponding measured target indices in the checked variant. Changing only the description will not change the sequence.

Change a target position or orientation

Need: move a Place destination within the existing scene.

Edit: a pose entry in targets.drop_pose.values. Positions are in meters; orientations are quaternions in XYZW order, so [0, 0, 0, 1] is identity. The absolute target is an object pose in the environment’s world frame, not a joint command or a TCP/end-effector pose. The integration uses the grasp relationship to determine robot motion. Do not add a TCP offset to the object target or interpret these numbers in a camera frame.

For the floor-standing cube, change the matching rest_pose XY too. Keep its center Z at 0.025 m only while the cube remains 5 cm tall and rests on this ground plane. Release Z and resting Z serve different purposes. Changing the quaternion changes the desired object orientation; the position-only validator does not verify it. Additional surfaces or objects require integration work.

Verify: change one pose at a time, run the checked program, and inspect the measured position error. Check reachability and scene clearance visually. The tutorial’s open-loop policy has dynamic collision checking disabled, so successful compilation does not establish clearance for arbitrary new targets. For other frames and semantic targets, see Scene registry.

Add another Pick/Place pair

Need: perform another move with the existing cube.

Edit: for the same pair of operations, increase program.count first. If the steps need different instructions or checks, use a sequence with explicit segment entries, following the complete structures in the downloadable files. Keep kind: invoke under steps and kind: pick / kind: place under call. Use object: cube and declare every referenced target.

This integration supports the Pick/Place workflow. A call being part of the language does not mean every deployment supports it. A second object, new robot, HandOver, or registered skill needs matching scene/resources/lowerers; follow Configure and Run an Embodied Task Program and registered calls.

Verify: check that the segment count and order match your intent, then rerun position/stability checks for every Place. Keep names useful for diagnosis and avoid assuming that a target advances merely because another call uses it.

Change task and segment language

Need: label the whole demonstration and its subgoals.

Edit: root instruction and each segment’s instruction in program.yaml. The root describes the episode; segment text describes that part of the task. For example, Move the cube to target B, then to target A. matches the modified program. Keep the wording consistent with the actual repeat count and target order. Do not change program_id to change the label.

Verify: after saving, run the Quickstart data reader and inspect the printed Task and segment instructions. Task language is stored in meta/tasks.parquet, segment language in meta/subtasks.parquet, with indices in frame data. See Task and segment language for expert data for overrides and training consumption.

Wait for settling and check the position

Need: reject a run when the cube does not settle near the requested location.

Edit: add post and validators to the Place segment in program.yaml, and provide separate resting targets. Use the complete checked program:

      post:
      - kind: wait_stable
        entity: cube
        preset: rigid_object
      validators:
      - kind: object_near_target
        object: cube
        target: rest_pose
        position_tolerance: 0.03

preset: rigid_object selects the integration’s existing stability preset; it is not a new tuning field. Post-policies run after the motion and before the validators. The position tolerance is a 3D distance, not a separate tolerance per axis. A settling timeout or failed validator rejects the affected row.

Verify: inspect metadata.post_policies and metadata.validation on each saved Place segment. The Quickstart’s observed errors are below 0.03 m. For a failed run, add --debug-mode to its no-save command to print the failed demo trace. Inspect the actual pose and settling status before changing the task. These checks do not independently prove grasp contact or release.

Change motion timing

Need: understand or adjust how long the robot takes to move.

Edit location: the execution-policy component selected by the deployment, not the program YAML. The Quickstart policy uses these actual fields:

policy_id: trajectory_open_loop_v1
preset_id: trajectory

requires:
  embodiment_contract: single_arm_parallel_gripper

motion:
  strategy: ik_interp
  velocity_targets: auto
  sample_count: 40
  dynamic_collision_mode: "off"

tracking:
  kind: timed

recovery:
  max_replans: 0
  max_action_retries: 0

workflow_recovery:
  max_recovery_attempts: 0

runner:
  minimum_cycle_time: 0.0
  hold_on_completion: false
  hold_during_effect_verification: false

effect_assurance: projected

In this ik_interp configuration, motion.sample_count: 40 generates 40 trajectory samples per Pick/Place. With the environment’s 0.04 s control interval, the observed unextended segments contain 40 steps (1.6 s of recorded time). Settling adds steps separately. tracking.kind: timed controls time-based tracking; runner.minimum_cycle_time is a runner cadence setting, not a uniform Cartesian speed command. Sample count is not a speed in meters per second, and its meaning is not interchangeable across motion strategies.

There is no general speed field on a repeat, segment or Pick/Place call. --task-program cannot override the execution policy. To change it, follow Configure and Run an Embodied Task Program to create a local deployment selecting a compatible policy, or choose an existing compatible deployment from the task catalog. Do not edit installed package files in place. Preserve policy/embodiment contracts and explicit assurance. This is an integration-author operation.

Verify: compare recorded segment lengths and physical acceptance at the same seed, and recheck reachability, settling and position. Only the displayed 40-sample policy is physically exercised in this tutorial; a timing change requires its own validation.

Choose another existing deployment

Need: use a supported robot or task without building an integration.

Edit: select its --gym_config package reference, using Task Catalog and show-task to discover it. First run its original program with its documented defaults. Reuse your local program only when its program_id, semantic entities, targets and calls satisfy the new deployment’s integration and contracts. Compatible embodiments can share a program; arbitrary tasks cannot.

The repeated Pick/Place Franka deployment does not enable expansion. Its UR5 counterpart selects an expansion declaration and can have different batch and collection defaults. Backend variants also select separate physical components; --physics is not a general way to turn any environment into another backend.

Verify: inspect the selected robot, backend, expanded segment count and collection settings, then run a single controlled episode and check the same physical criteria. Single-environment success does not qualify randomized or batch execution. For new scene/robot ownership, continue with Configure and Run an Embodied Task Program, Scene registry and Robot skill profiles.