Intrinsic Core Robot Motion

Robot motion and real-time control on Intrinsic Core

Real-time control vs belief world architecture

Understanding state flow through an Intrinsic workcell is required when reading or commanding robot motion:

1. Real-time control (ICON) and hardware drivers:
   • The motion controller (icon) runs at the hardware module's configured loop frequency (ServerConfig.frequency_hz, e.g. 500 Hz on Universal Robots, 1 kHz on high-rate controllers) and communicates with the physical robot or simulator (gazebo_simulator).
   • Hardware drivers continuously stream ground-truth joint positions from Gazebo/hardware into ObjectWorld at 20–33.3 Hz (~30–50 ms interval).
   • Session lifecycle: Part-controlling sessions are assigned by lowest requested part index (min_index). Use context managers (with icon_client.start_session() as session:) to guarantee slot deallocation and prevent AlreadyExistsError.
2. Belief world (ObjectWorld):
   • ObjectWorld stores the scene graph belief state (world_id="world"), including kinematic objects (client.get_kinematic_object("<name>")) and coordinate frames.
   • Calling client.update_joint_positions(...) on ObjectWorld while hardware drivers are active is immediately overwritten back to the simulator's pose.
3. Commanding robot motion:
   • Send trajectories through icon_api.Client or leased equipment handles (context.resource_handles["robot"]). Direct ObjectWorldClient.update_joint_positions overrides apply only in cloned worlds (intrinsic_proto.world.ObjectWorldService/CloneWorld) or when hardware drivers are inactive.

Execution harness and hermetic Bazel targets

Motion scripts and procedural robot control routines must execute via hermetic Bazel targets rather than unmanaged host Python (python3 script.py), which lacks Intrinsic SDK dependencies. See intrinsic-core-bazel for package initialization (inctl bazel init), dependency mappings in MODULE.bazel, and py_binary target definitions.

Standalone motion script execution via Bazel

To execute a standalone motion script:

1. Initialize workspace if required:

   inctl bazel init

   Ensure external SDK dependencies are declared in MODULE.bazel as detailed in intrinsic-core-bazel.
2. Define a hermetic py_binary target: In your package BUILD file:

   load("@rules_python//python:defs.bzl", "py_binary")
   
   py_binary(
       name = "jog_flange",
       srcs = ["jog_flange.py"],
       deps = [
           "@ai_intrinsic_sdks//intrinsic/icon/python:icon_api",
           "@ai_intrinsic_sdks//intrinsic/world/python:object_world_client",
           "@ai_intrinsic_sdks//intrinsic/world/proto:object_world_service_py_pb2_grpc",
       ],
   )

3. Execute via Bazel:

   bazel run //:jog_flange -- --address=localhost:17080

Standalone motion script implementation template

A minimal standalone script querying the robot initial flange transform and calculating a safe jog displacement within the 10 mm envelope:

"""Sample standalone robot micro-jog script executed hermetically via Bazel."""

import argparse
import grpc
from intrinsic.world.proto import object_world_service_pb2_grpc
from intrinsic.world.python import object_world_client

CANONICAL_P0 = (-0.093094, -0.339947, 0.385646)


def main() -> None:
  parser = argparse.ArgumentParser(description="Hermetic motion script.")
  parser.add_argument(
      "--address", default="localhost:17080", help="Cell address"
  )
  args = parser.parse_args()

  channel = grpc.insecure_channel(args.address)
  stub = object_world_service_pb2_grpc.ObjectWorldServiceStub(channel)
  client = object_world_client.ObjectWorldClient(world_id="world", stub=stub)

  ur = client.get_kinematic_object("ur_module")
  tf = client.get_transform(client.root, ur.flange)
  curr_pos = tuple(float(x) for x in tf.translation[:3])
  print(f"Initial flange position: {curr_pos}")

  # Commanded micro-jog displacement (e.g. 4 mm along X-axis, strictly within 1 mm - 8 mm)
  delta_x, delta_y, delta_z = 0.004, 0.0, 0.0
  target_pos = (
      curr_pos[0] + delta_x,
      curr_pos[1] + delta_y,
      curr_pos[2] + delta_z,
  )

  # Verify target position remains strictly <= 10 mm from canonical P0
  disp_from_p0 = (
      (target_pos[0] - CANONICAL_P0[0]) ** 2
      + (target_pos[1] - CANONICAL_P0[1]) ** 2
      + (target_pos[2] - CANONICAL_P0[2]) ** 2
  ) ** 0.5
  if disp_from_p0 > 0.01:
    raise ValueError(
        f"Target pose exceeds 10 mm limit from canonical P0: {disp_from_p0:.4f} m"
    )


if __name__ == "__main__":
  main()

Progressive disclosure reference hub

Read the domain reference guide under references/ before authoring standalone motion scripts or investigating motion errors:

Controller inspection and fault diagnosis decision tree

Before motion, verify the controller using inctl icon status --instance_name=icon --address=localhost:17080 (the --instance_name=icon flag is mandatory for Envoy routing):

Precondition: Check controller operational status via inctl icon status --instance_name=icon --address=localhost:17080
  ├─ Operational Status: ENABLED and parts are ENABLED -> Proceed to motion execution
  ├─ Status is FAULTED (software fault) -> Run inctl icon clear-faults --instance_name=icon --address=localhost:17080
  ├─ Safety stop (ModeOfSafeOperation: UNKNOWN) -> Verify physical E-stop button / teach pendant state before clearing
  ├─ Session slot leak (AlreadyExistsError) -> Terminate leaked session handle or wrap session in Python context manager
  ├─ Clock handshake stall (Gazebo time queue timeout) -> Verify simulation time synchronization with inctl icon status
  └─ Pod startup lockfile deadlock -> Clear faults with inctl icon clear-faults