Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions NOTICE
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
EmbodiChain
Copyright (c) 2021-2026 DexForce Technology Co., Ltd.

The cable routing application includes geometry and routines adapted from
RoboSimStudio, Copyright 2026 Kaiyuan Chen, licensed under Apache-2.0.
Source: https://github.com/robosimstudio/robosimstudio
Revision: 73739abe212f963e8a9f5862b27bca370df091a7

The external YAM i2rt model contains the YAM arm and linear_4310 gripper,
Copyright (c) I2RT Robotics, under the MIT license. The source model directory
and RoboSimStudio NOTICE identify this attribution and license.
Expand Down
2 changes: 1 addition & 1 deletion agent_context/MAP.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,7 @@ topics:
- id: atomic-actions
title: Atomic Skills
aliases: [atomic skill, atomic skills, atomic action, 原子技能, 原子动作]
keywords: [PlanningBudget, PlanningRecovery, ExecutionPlanLifecycle, AtomicSkillEngine, run-atomic-skill, PlanningContext, ExecutionSession, ExecutionRunner, SkillInvocation,
keywords: [PlanningBudget, PlanningRecovery, ExecutionPlanLifecycle, PickUp, GraspGoal, ContactGraspGoal, AtomicSkillEngine, run-atomic-skill, PlanningContext, ExecutionSession, ExecutionRunner, SkillInvocation,
hand_geometry_cfgs, GraspOpeningTarget, prepare_grasp_query, scoped grasp preparation,
RecoveryPolicy, HeldObjectGuardRequest, PhaseEffectGateRequest, articulation_geometry, control-grid retiming,
AffordanceSamplingContext, AffordancePoseCandidates, AffordanceSample, affordance sampling]
Expand Down
21 changes: 21 additions & 0 deletions agent_context/topics/atomic-actions/atomic-actions.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,27 @@ Hosts acquire versioned measurements; verification is the boundary that commits
or invalidates observed effects. Preserve required stop/hold boundaries on the
executed control grid instead of relying only on native planner timing.

`PickUp` accepts a rigid `GraspGoal` or an explicit `ContactGraspGoal`.
The rigid path projects its existing held-object relation. Contact pickup
requires a free task-state resource, shares the approach/close/lift command
assembly and declares `EffectVerificationRequirement(kind="contact_grasp")`
without a rigid held-object update. Hosts supply physical evidence such as
material-point lift and tool-frame retention before accepting that boundary.
The routing host samples its material reference at the end of the `close`
phase, including `grasp_settle_steps`, before lifting. Native contact IK paths
use `MotionPolicy.interpolate_position_step` for lift sampling on the control
grid; joint limits can lengthen them. Numerical material-coordinate geometry
belongs to `compute/geometry/cable.py`.

`ContactPickUpGoal` and `ContactPlaceGoal` opt into a bounded observed path in
the same `PickUp`/`Place` invocation. `SkillPlan.continuation` carries an owned
cursor; `ExecutionSession` installs the next plan only after the host acknowledges
commands and physical checkpoints. The engine owns motion generation; the
episode-owned `ContactPhaseSource` resolves geometry and observations only.
Offline projection, external trajectory transforms, replay recovery and
invocation revisions are rejected for this path. Its phases share one timeout
and failure scope; `SkillPlan.segments` remain descriptive command ranges.

Row-local planning within a larger World must carry the same explicit
`context.env_ids` through FK/IK, root poses and diagnostics. HandOver applies this
to both source/destination arms, including its continuation and failed-waypoint
Expand Down
9 changes: 9 additions & 0 deletions agent_context/topics/atomic-actions/execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,15 @@ implementation `_plan(request, context)` hook.
- `ExecutionRunner` drives that session against observation, command, and clock
ports without blocking `step()`.

An opt-in `SkillPlan.continuation` requests fresh-observation planning inside
one invocation. Progress is bounded and strictly advances; rejected rows cannot
return. `PLAN_CONTINUED` records each installed chunk without consuming a retry
or resetting the invocation timeout. Intermediate chunks commit no symbolic
effects. Contact paths require execution, reject offline `compile()`, external
nominal/expanded trajectories and invocation revisions, and retain loaded joint
targets across internal holds. `PlanningContext.planning_mask` scopes geometric
reductions and IK to the session's eligible rows before selecting shared timing.

For a prequalified replay, `MoveJoints` accepts a typed full-robot
`TimedTrajectory`. Each command occupies one environment control step.
The motion binding covers all joints, and the selected rows match the planning
Expand Down
10 changes: 8 additions & 2 deletions agent_context/topics/simulation-system/deformables.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,14 @@ Focused coverage: `tests/sim/test_deformable_cfg.py`,
`CableObjectCfg` and `CableObject(BatchEntity)` are independent of particle-set
deformables. `SimulationManager.add_cable_object()` lowers through
`spawn/descriptors.py` into `CableDesc`, declares in the existing `SpawnScene`,
and binds the same facade in place during `prepare()`. Backend capabilities
reject Default, CPU, other Newton solvers and gradient mode; use DexUni on CUDA.
and binds the same facade in place during `prepare()`. `add_usd(UsdImportCfg)`
also returns a `CableObject` per imported cable under its source resource key,
with the same UID lookup, segment state and reset as a procedural declaration.
Cable geometry, placement and visuals come from the parsed `CableDesc`.
A sparse `asset_cfgs` entry keyed by the simulation curve prim can override
the UID, `fixed_segments`, `collision_filter_span` and individual `attrs` physics and
contact fields before declaration. Omitted fields retain the parsed values.
Cable declarations require DexUni on CUDA with gradient mode disabled.
With this backend, an arena containing a cable cannot also contain fluid,
cloth or soft-body particles: cable episode reset does not support those
particles. Spawn checks the native cable and particle descriptors for direct
Expand Down
27 changes: 27 additions & 0 deletions agent_context/topics/task-programs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,15 @@ the closed-field decoder. Omitting `velocity_limit` preserves the Robot's
ordered per-joint speed caps; an explicit scalar request is intersected with
those caps rather than replacing them.

Configured motion accepts `interpolate_position_step` for native Cartesian
sampling. `MoveEndEffectorOptions.preserve_cartesian_samples` retains authored
Cartesian samples; `MoveJointsOptions.preserve_samples` consumes explicitly
sampled joint commands at the host cadence using `ik_interp`. The joint speed
check includes the step from the observed posture to the first command and every
subsequent step. Each row must satisfy the effective per-joint limits.
Registration fingerprints include shared skill goal types and declared motion
policies, even when a deployment uses their defaults.

Configured motion also accepts explicit `interpolation_mode` and `ik_seed_mode`.
`fixed_grid` requires `acceleration_limit: null` and no scalar speed override;
omission retains the existing adaptive policy and acceleration default.
Expand All @@ -268,6 +277,24 @@ declarations in the integration and timing in the execution policy, rather
than placing a precomputed bottle world pose in the program. Omitting `target`
retains the original internal-axis pouring behavior.

`scene_binding.cables` declares material-state native identities without rigid
object semantics or root-pose providers. The allowlisted
`runtime_services.cable_material` binds those identities to measured material
coordinates and closed target declarations. Declared contact operations lower
to `PickUp(ContactPickUpGoal)` and `Place(ContactPlaceGoal)`; bounded observed
continuations keep feedback phases inside the same invocation. The program
owns operation ordering. Compatibility move/joint/check adapters retain their
explicit configured call contracts. Registered grounding receives eligible rows
through `PlanningContext.planning_mask`, before shared duration reductions.
The bridge captures contact references only after an
acknowledged close frame and checks material slip after every consumed action.
Measured cable conditions reject individual eligible rows. Healthy rows continue
to the next stage.
References are fresh per bridge, guarded by its episode scope, and mapped from
selected robot rows to native cable arenas. Evaluation consumes qualified
`cables/<uid>/<measurement>` channels, including strict endpoint geometry and
episode slip. Keep routing acceptance in the deployment's named evaluation rules.

The configured lowerer allowlist also exposes profile-owned Park, AxisAlign,
relative Place and coordinated transport. Their declarations in
`integrations/_configured_services.py` select exact Atomic Skill descriptors;
Expand Down
111 changes: 111 additions & 0 deletions docs/source/api_reference/public_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,19 @@ Chunked planar distances preserve tensor batch axes, dtype and device.

.. autofunction:: signed_distance_to_polygon

embodichain.compute.geometry.cable
----------------------------------

Pure tensor geometry for ordered cable endpoints, material-coordinate sampling
and slip of the same material point in a moving tool frame.

.. currentmodule:: embodichain.compute.geometry.cable

.. autosummary::

sample_cable_material
cable_endpoints
cable_grasp_slip

embodichain.compute.geometry.particles
--------------------------------------
Expand Down Expand Up @@ -3486,6 +3499,22 @@ embodichain.lab.sim.atomic_skills.primitives

BUILTIN_SKILL_TYPES

embodichain.lab.sim.atomic_skills.primitives.pick_up
--------------------------------------------------

PickUp shares motion assembly between rigid-object pickup and contact-only
pickup. Contact goals require explicit physical verification and retain no
fixed object-to-tool relation.

.. currentmodule:: embodichain.lab.sim.atomic_skills.primitives.pick_up

.. autosummary::

GraspGoal
ContactGraspGoal
PickUp
PickUpOptions

embodichain.lab.sim.atomic_skills.requirements
-----------------------------------------------

Expand Down Expand Up @@ -5137,6 +5166,19 @@ reference-state resets and terminal snapshots before automatic row resets.
.. automodule:: embodichain_tasks.locomotion.tracking.g1_motion
:members:

embodichain_tasks.manipulation.cable.route_the_cable
----------------------------------------------------

Two-spool routing with observed material geometry and measured grasp-slip,
penetration and end-insertion acceptance.

.. currentmodule:: embodichain_tasks.manipulation.cable.route_the_cable

.. autosummary::

RouteTheCableEnv
measure_route

embodichain_tasks.manipulation.push_cube
----------------------------------------

Expand Down Expand Up @@ -7062,3 +7104,72 @@ Official sensor presets

VLP16Cfg
VLP16_REGISTRATION


Observed contact manipulation
=============================

The existing ``PickUp`` and ``Place`` skills accept explicit contact paths.
These keep one invocation while planning later chunks from fresh measurements;
no rigid held-object relation or independently recoverable sub-skill is implied.
The host must acknowledge commands and acquire the declared physical evidence.
Paths reject offline projection, external trajectory transformations, replay
recovery and mid-operation invocation revisions.

Bounded plan continuation
-------------------------

.. currentmodule:: embodichain.lab.sim.atomic_skills.continuation

.. autosummary::

PlanContinuation
PlanContinuationResult

.. autoclass:: PlanContinuation
:members:

.. autoclass:: PlanContinuationResult
:members:

Contact goals and observation sources
-------------------------------------

.. currentmodule:: embodichain.lab.sim.atomic_skills.primitives.contact

The source is registered through ``SkillPlanningServices.register_contact_source``
and remains owned by its episode host. It resolves geometric snapshots and
accepts observed physical boundaries; motion generation and simulation stepping
remain with the engine and host respectively. Snapshots retain owned tensors
and scalar metadata, with explicit batch and row identity.

.. autosummary::

ContactPhase
ContactPostcondition
ContactPickUpGoal
ContactPlaceGoal
ContactPhaseSource
ContactContinuation
ResolvedContactPhase

.. autoclass:: ContactPhase
:members:

.. autoclass:: ContactPostcondition
:members:

.. autoclass:: ContactPickUpGoal
:members:

.. autoclass:: ContactPlaceGoal
:members:

.. autoclass:: ContactPhaseSource
:members:

.. autoclass:: ContactContinuation
:members:

.. autoclass:: ResolvedContactPhase
:members:
28 changes: 21 additions & 7 deletions docs/source/overview/sim/atomic_skills/builtin_skills.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@ The animations below are the runnable simulator demonstrations under
|---|---|---|---|---|---|
| `move_end_effector` | `EndEffectorPoseGoal` | `primary.motion` | none | none | none |
| `move_joints` | `JointPositionGoal` | `primary.motion` | named target only: command matching `target` on `primary.motion` | none | none |
| `pick_up` | `GraspGoal` | `primary.motion`, `primary.grasp` | `primary.grasp`: `open`, `grasp` | semantic object/entity | attach object to the `primary.motion` target |
| `pick_up` | `GraspGoal` or `ContactGraspGoal` | `primary.motion`, `primary.grasp` | `primary.grasp`: `open`, `grasp` | semantic object or explicit contact pose | rigid held relation or terminal contact verification |
| `axis_align` | `AxisAlignGoal` | `primary.motion`, `primary.grasp` | `primary.grasp`: `open`, `grasp` | unheld object with `AxisAlignAffordance` | open-loop pick and align while retaining the grasp |
| `move_held_object` | `HeldObjectPoseGoal` | `primary.motion`, `primary.grasp` | `primary.grasp`: `grasp` | object held exclusively by the `primary.motion` target | preserve attachment |
| `pour` | `PourGoal` | `primary.motion`, `primary.grasp` | `primary.grasp`: `grasp` | exclusively held object with `AxisAlignAffordance` | preserve attachment; open-loop rotate and return |
Expand Down Expand Up @@ -410,17 +410,31 @@ named_goal = JointPositionGoal(target="home")

## `PickUp`

Plans **approach -> close hand -> lift** and declares the object attached to the
bound motion target.
Plans **approach -> close hand -> lift**. A rigid `GraspGoal` declares a held-object
relation for the bound motion target. `ContactGraspGoal(grasp_xpos=...)` uses an
observed TCP pose and requires physical contact verification, with no fixed
object-to-tool relation.

| Contract | Value |
|---|---|
| Skill ID | `pick_up` |
| Goal | `GraspGoal(semantics=..., grasp_xpos=None, object_pose=None)` |
| Goal | `GraspGoal(semantics=..., grasp_xpos=None, object_pose=None)` or `ContactGraspGoal(grasp_xpos=...)` |
| Binding contract | `primary.motion` plus disjoint `primary.grasp` |
| Precondition | When `object_pose` is omitted, `ObjectSemantics.entity_id` must resolve in the planning snapshot (the deprecated live `entity` fallback remains temporarily); an explicit `SceneEntityPose` must reference a snapshot entity; an `AntipodalAffordance` is required when neither an explicit grasp pose nor `fixed_object_to_eef` is supplied |
| Effect | write `HeldObjectState` for the bound motion target |
| Verification | the attachment effect must be verified during closed-loop execution |
| Precondition | Rigid goals resolve their object pose and require an affordance when no grasp is supplied; contact goals require a free task-state resource; late-bound poses resolve in the planning snapshot |
| Effect | Rigid goals write `HeldObjectState`; contact goals declare a physical verification requirement |
| Verification | Rigid held effects and contact-only grasp effects require physical verification during closed-loop execution |

Contact goals require an unoccupied single/coordinated task-state resource.
Their plan declares `EffectVerificationRequirement(kind="contact_grasp")`,
which the host must resolve with physical evidence. The cable routing host
measures material-point lift and retention in the tool frame. Rigid-object
calibrations and downstream object targets belong to `GraspGoal` pickup.

Contact pickup uses the existing `hand_interp_steps`, `grasp_settle_steps` and
`lift_height` options. Its native IK lift is sampled using
`MotionPolicy.interpolate_position_step` and the control period, then qualified
against joint limits. The motion-generator and external-nominal paths retain
their backend timing. Both goal types use the same effect assembly boundary.

`grasp_xpos` may be `(4, 4)`, `(B, 4, 4)`, or a `SceneEntityPose`. A scene
reference resolves the latest grasp pose and registers its entity as a recovery
Expand Down
Loading
Loading