Viam SDK
    Preparing search index...

    Interface Motion

    A service that coordinates motion planning across all of the components in a given robot.

    interface Motion {
        getPlan: (
            componentName: string,
            lastPlanOnly?: boolean,
            executionId?: string,
            extra?: Struct,
        ) => Promise<motionApi.GetPlanResponse>;
        getPose: (
            componentName: string,
            destinationFrame: string,
            supplementalTransforms: PlainMessage<commonApi.Transform>[],
            extra?: Struct,
        ) => Promise<PlainMessage<commonApi.PoseInFrame>>;
        listPlanStatuses: (
            onlyActivePlans?: boolean,
            extra?: Struct,
        ) => Promise<motionApi.ListPlanStatusesResponse>;
        move: (
            destination: PoseInFrame,
            componentName: string,
            worldState?: PlainMessage<commonApi.WorldState>,
            constraints?: PlainMessage<motionApi.Constraints>,
            extra?: Struct,
        ) => Promise<boolean>;
        moveOnGlobe: (
            destination: GeoPoint,
            componentName: string,
            movementSensorName: string,
            heading?: number,
            obstaclesList?: PlainMessage<commonApi.GeoGeometry>[],
            motionConfiguration?: PlainMessage<motionApi.MotionConfiguration>,
            boundingRegion?: PlainMessage<commonApi.GeoGeometry>[],
            extra?: Struct,
        ) => Promise<string>;
        moveOnMap: (
            destination: Pose,
            componentName: string,
            slamServiceName: string,
            motionConfiguration?: PlainMessage<motionApi.MotionConfiguration>,
            obstacles?: PlainMessage<commonApi.Geometry>[],
            extra?: Struct,
        ) => Promise<string>;
        name: string;
        stopPlan: (componentName: string, extra?: Struct) => Promise<null>;
        doCommand(command: Struct | Record<string, JsonValue>): Promise<JsonValue>;
        getStatus(): Promise<JsonValue>;
    }

    Hierarchy (View Summary)

    Implemented by

    Index

    Properties

    getPlan getPose listPlanStatuses move moveOnGlobe moveOnMap name stopPlan

    Methods

    doCommand getStatus

    Properties

    getPlan: (
        componentName: string,
        lastPlanOnly?: boolean,
        executionId?: string,
        extra?: Struct,
    ) => Promise<motionApi.GetPlanResponse>

    By default: returns the plan history of the most recent moveOnGlobe() or moveOnMap() call to move a component. The plan history for executions before the most recent can be requested by providing an ExecutionID in the request. Returns a result if both of the following conditions are met:

    • The execution (call to moveOnGlobe() or moveOnMap()) is still executing or changed state within the last 24 hours
    • The robot has not reinitialized

    Plans never change. Replans always create new plans. Replans share the ExecutionID of the previously executing plan. All repeated fields are in chronological order.

    Type Declaration

      • (
            componentName: string,
            lastPlanOnly?: boolean,
            executionId?: string,
            extra?: Struct,
        ): Promise<motionApi.GetPlanResponse>

      • Parameters

        • componentName: string

          The component to query

        • OptionallastPlanOnly: boolean
        • OptionalexecutionId: string
        • Optionalextra: Struct

        Returns Promise<motionApi.GetPlanResponse>

    const motion = new VIAM.MotionClient(machine, 'builtin');
    const baseName = 'my_base';

    // Get the plan(s) of the base component
    const response = await motion.getPlan(baseName);

    For more information, see Motion API.

    getPose: (
        componentName: string,
        destinationFrame: string,
        supplementalTransforms: PlainMessage<commonApi.Transform>[],
        extra?: Struct,
    ) => Promise<PlainMessage<commonApi.PoseInFrame>>

    Get the current location and orientation of a component.

    Type Declaration

    Use RobotClient.getPose instead.

    const motion = new VIAM.MotionClient(machine, 'builtin');

    const gripperName = 'my_gripper';

    // Get the gripper's pose in world coordinates
    const gripperPoseInWorld = await motion.getPose(gripperName, 'world', []);

    For more information, see Motion API.

    listPlanStatuses: (
        onlyActivePlans?: boolean,
        extra?: Struct,
    ) => Promise<motionApi.ListPlanStatusesResponse>

    Returns the statuses of plans created by MoveOnGlobe calls that meet at least one of the following conditions since the motion service initialized:

    • The plan's status is in progress
    • The plan's status changed state within the last 24 hours

    All repeated fields are in chronological order.

    Type Declaration

    const motion = new VIAM.MotionClient(machine, 'builtin');

    // List plan statuses within the TTL
    const response = await motion.listPlanStatuses();

    For more information, see Motion API.

    move: (
        destination: PoseInFrame,
        componentName: string,
        worldState?: PlainMessage<commonApi.WorldState>,
        constraints?: PlainMessage<motionApi.Constraints>,
        extra?: Struct,
    ) => Promise<boolean>

    Move any component on the robot to a specified destination which can be from the reference frame of any other component on the robot.

    Type Declaration

      • (
            destination: PoseInFrame,
            componentName: string,
            worldState?: PlainMessage<commonApi.WorldState>,
            constraints?: PlainMessage<motionApi.Constraints>,
            extra?: Struct,
        ): Promise<boolean>

      • Parameters

        • destination: PoseInFrame

          Destination to move to, which can a pose in the reference frame of any frame in the robot's frame system.

        • componentName: string

          Component on the robot to move to the specified destination.

        • OptionalworldState: PlainMessage<commonApi.WorldState>

          Avoid obstacles by specifying their geometries in the world state. Augment the frame system of the robot by specifying additional transforms to add to it for the duration of the Move.

        • Optionalconstraints: PlainMessage<motionApi.Constraints>

          Constrain the way the robot will move.

        • Optionalextra: Struct

        Returns Promise<boolean>

    const motion = new VIAM.MotionClient(machine, 'builtin');

    // Assumes a gripper configured with name "my_gripper"
    cconst gripperName = "my_gripper";

    const goalPose: VIAM.Pose = {
      x: -817,
      y: -230,
      z: 62,
      oX: -1,
      oY: 0,
      oZ: 0,
      theta: 90,
    };
    const goalPoseInFrame = new VIAM.PoseInFrame({
      referenceFrame: 'world',
      pose: goalPose,
    });

    // Move the gripper
    const moved = await motion.move(goalPoseInFrame, gripperName);

    For more information, see Motion API.

    moveOnGlobe: (
        destination: GeoPoint,
        componentName: string,
        movementSensorName: string,
        heading?: number,
        obstaclesList?: PlainMessage<commonApi.GeoGeometry>[],
        motionConfiguration?: PlainMessage<motionApi.MotionConfiguration>,
        boundingRegion?: PlainMessage<commonApi.GeoGeometry>[],
        extra?: Struct,
    ) => Promise<string>

    Move a component to a specific latitude and longitude, using a MovementSensor to check the location. moveOnGlobe() is non blocking, meaning the motion service will move the component to the destination GPS point after moveOnGlobe() returns. Each successful moveOnGlobe() call retuns a unique ExectionID which you can use to identify all plans generated durring the moveOnGlobe() call. You can monitor the progress of the moveOnGlobe() call by querying getPlan() and listPlanStatuses().

    Type Declaration

    const motion = new VIAM.MotionClient(machine, 'builtin');

    // Define destination at GPS coordinates [0,0]
    const destination: VIAM.GeoPoint = {
      latitude: 40.7,
      longitude: -73.98,
    };

    const baseName = 'my_base';
    const movementSensorName = 'my_movement_sensor';

    // Move the base to the geographic location
    const globeExecutionId = await motion.moveOnGlobe(
      destination,
      baseName,
      movementSensorName,
    );

    For more information, see Motion API.

    moveOnMap: (
        destination: Pose,
        componentName: string,
        slamServiceName: string,
        motionConfiguration?: PlainMessage<motionApi.MotionConfiguration>,
        obstacles?: PlainMessage<commonApi.Geometry>[],
        extra?: Struct,
    ) => Promise<string>

    Move a component to a Pose in respect to the origin of the SLAM map, using a SLAM service to check the location. moveOnMap()is non blocking, meaning the motion service will move the component to the destination Pose aftermoveOnMap()returns. Each successfulmoveOnMap()call retuns a unique ExectionID which you can use to identify all plans generated durring themoveOnMap()call. You can monitor the progress of themoveOnMap()call by queryinggetPlan()andlistPlanStatuses()`.

    Type Declaration

      • (
            destination: Pose,
            componentName: string,
            slamServiceName: string,
            motionConfiguration?: PlainMessage<motionApi.MotionConfiguration>,
            obstacles?: PlainMessage<commonApi.Geometry>[],
            extra?: Struct,
        ): Promise<string>

      • Parameters

        • destination: Pose

          Specify a destination to, which can be any Pose with respect to the SLAM map's origin.

        • componentName: string

          Component on the robot to move to the specified destination.

        • slamServiceName: string

          Name of the SLAM service from which the SLAM map is requested

        • OptionalmotionConfiguration: PlainMessage<motionApi.MotionConfiguration>

          Optional motion configuration options.

        • Optionalobstacles: PlainMessage<commonApi.Geometry>[]

          Optional obstacles to be considered for motion planning.

        • Optionalextra: Struct

        Returns Promise<string>

    const motion = new VIAM.MotionClient(machine, 'builtin');

    // Define destination pose with respect to map origin
    const myPose: VIAM.Pose = {
      x: 0,
      y: 10,
      z: 0,
      oX: 0,
      oY: 0,
      oZ: 0,
      theta: 0,
    };

    const baseName = 'my_base';
    const slamServiceName = 'my_slam_service';

    // Move the base to Y=10 (location of 0,10,0) relative to map origin
    const executionId = await motion.moveOnMap(myPose, baseName, slamServiceName);

    For more information, see Motion API.

    name: string

    The name of the resource.

    stopPlan: (componentName: string, extra?: Struct) => Promise<null>

    Stop a component being moved by an in progress moveOnGlobe() or moveOnMap() call.

    Type Declaration

      • (componentName: string, extra?: Struct): Promise<null>

      • Parameters

        • componentName: string

          The component to stop

        • Optionalextra: Struct

        Returns Promise<null>

    const motion = new VIAM.MotionClient(machine, 'builtin');
    const baseName = 'my_base';

    // Stop the base component which was instructed to move
    await motion.stopPlan(baseName);

    For more information, see Motion API.

    Methods

    • Send/Receive arbitrary commands to the resource.

      Parameters

      • command: Struct | Record<string, JsonValue>

        The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.

      Returns Promise<JsonValue>

      // Plain object (recommended)
      const result = await resource.doCommand({
        myCommand: { key: 'value' },
      });

      // Struct (still supported)
      import { Struct } from '@viamrobotics/sdk';

      const result = await resource.doCommand(Struct.fromJson({ myCommand: { key: 'value' } }));

    Settings

    Member Visibility

    On This Page

    Properties
    Methods