Gantry API

The gantry API allows you to give commands to your gantry components for coordinated control of one or more linear actuators.

The gantry component supports the following methods:

Method NameDescription
GetPositionGet the current positions of the axis of the gantry (mm).
MoveToPositionMove the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
GetLengthsGet the lengths of the axes of the gantry (mm).
HomeRun the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
GetGeometriesGet all the geometries associated with the gantry in its current configuration, in the frame of the gantry.
IsMovingGet if the gantry is currently moving.
StopStop all motion of the gantry.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
GetResourceNameGet the ResourceName for this gantry with the given name.
CloseSafely shut down the resource and prevent further use.

Establish a connection

To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page on the Viam app, navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

When executed, this sample code creates a connection to your machine as a client.

The following examples assume you have a gantry called "my_gantry" configured as a component of your machine. If your gantry has a different name, change the name in the code.

Be sure to import the gantry package for the SDK you are using:

from viam.components.gantry import Gantry
import (
  "go.viam.com/rdk/components/gantry"
)

API

GetPosition

Get the current positions of the axis of the gantry (mm).

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (List[float]): A list of the position of the axes of the gantry in millimeters.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

# Get the current positions of the axes of the gantry in millimeters.
positions = await my_gantry.get_position()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • ([]float64): A list of the position of the axes of the gantry in millimeters.
  • (error): An error, if one occurred.

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

// Get the current positions of the axes of the gantry in millimeters.
position, err := myGantry.Position(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

var position = await myGantry.position();

For more information, see the Flutter SDK Docs.

MoveToPosition

Move the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).

Parameters:

  • positions (List[float]) (required): A list of positions for the axes of the gantry to move to, in millimeters.
  • speeds (List[float]) (required): A list of speeds in millimeters per second for the gantry to move at respective to each axis.
  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • None.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

# Create a list of positions for the axes of the gantry to move to. Assume in
# this example that the gantry is multi-axis, with 3 axes.
examplePositions = [1, 2, 3]

exampleSpeeds = [3, 9, 12]

# Move the axes of the gantry to the positions specified.
await my_gantry.move_to_position(
    positions=examplePositions, speeds=exampleSpeeds)

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • positionsMm ([]float64): A list of positions for the axes of the gantry to move to, in millimeters.
  • speedsMmPerSec ([]float64): A list of speeds in millimeters per second for the gantry to move at respective to each axis.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (error): An error, if one occurred.

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

// Create a list of positions for the axes of the gantry to move to.
// Assume in this example that the gantry is multi-axis, with 3 axes.
examplePositions := []float64{1, 2, 3}

exampleSpeeds := []float64{3, 9, 12}

// Move the axes of the gantry to the positions specified.
myGantry.MoveToPosition(context.Background(), examplePositions, exampleSpeeds, nil)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

await myGantry.moveToPosition([0.0, 20.5], [15, 15]);

For more information, see the Flutter SDK Docs.

GetLengths

Get the lengths of the axes of the gantry (mm).

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (List[float]): A list of the lengths of the axes of the gantry in millimeters.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

# Get the lengths of the axes of the gantry in millimeters.
lengths_mm = await my_gantry.get_lengths()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • ([]float64): A list of the lengths of the axes of the gantry in millimeters.
  • (error): An error, if one occurred.

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

// Get the lengths of the axes of the gantry in millimeters.
lengths_mm, err := myGantry.Lengths(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

var lengths = await myGantry.lengths();

For more information, see the Flutter SDK Docs.

Home

Run the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (bool): Whether the gantry has run the homing sequence successfully.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

await my_gantry.home()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (bool): Whether the gantry has run the homing sequence successfully.
  • (error): An error, if one occurred.

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

myGantry.Home(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

var homed = await myGantry.home();

For more information, see the Flutter SDK Docs.

GetGeometries

Get all the geometries associated with the gantry in its current configuration, in the frame of the gantry. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

Example:

geometries = await my_gantry.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")

For more information, see the Python SDK Docs.

IsMoving

Get if the gantry is currently moving.

Parameters:

  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (bool): Whether the gantry is moving.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

# Stop all motion of the gantry. It is assumed that the
# gantry stops immediately.
await my_gantry.stop()

# Print if the gantry is currently moving.
print(my_gantry.is_moving())

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (bool): Whether this resource is moving (true) or not (false).
  • (error): An error, if one occurred.

Example:

// This example shows using IsMoving with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

// Stop all motion of the arm. It is assumed that the arm stops immediately.
myArm.Stop(context.Background(), nil)

// Log if the arm is currently moving.
is_moving, err := myArm.IsMoving(context.Background())
logger.Info(is_moving)

For more information, see the Go SDK Docs.

Parameters:

  • None.

Returns:

Example:

var moving = await myGantry.isMoving();

For more information, see the Flutter SDK Docs.

Stop

Stop all motion of the gantry.

Parameters:

  • extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • None.

Example:

my_gantry = Gantry.from_robot(robot=robot, name="my_gantry")

# Stop all motion of the gantry. It is assumed that the gantry stops
# immediately.
await my_gantry.stop()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (error): An error, if one occurred.

Example:

// This example shows using Stop with an arm component.
myArm, err := arm.FromRobot(machine, "my_arm")

// Stop all motion of the arm. It is assumed that the arm stops immediately.
err = myArm.Stop(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

await myGantry.stop();

For more information, see the Flutter SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • deps (Dependencies): The resource dependencies.
  • conf (Config): The resource configuration.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. For built-in models, model-specific commands are covered with each model’s documentation. If you are implementing your own gantry and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

  • command (Mapping[str, ValueTypes]) (required): The command to execute.
  • timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

  • (Mapping[str, viam.utils.ValueTypes]): Result of the executed command.

Raises:

  • (NotImplementedError): Raised if the Resource does not support arbitrary commands.

Example:

command = {"cmd": "test", "data1": 500}
result = await my_gantry.do_command(command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myGantry.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

// Example using doCommand with an arm component
const command = {'cmd': 'test', 'data1': 500};
var result = myArm.doCommand(command);

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this gantry with the given name.

Parameters:

  • name (str) (required): The name of the Resource.

Returns:

Example:

my_gantry_name = Gantry.get_resource_name("my_gantry")

For more information, see the Python SDK Docs.

Parameters:

Returns:

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

await my_gantry.close()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error): An error, if one occurred.

Example:

myGantry, err := gantry.FromRobot(machine, "my_gantry")

err = myGantry.Close(context.Background())

For more information, see the Go SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.