Edit

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 Name	Description
`GetPosition`	Get the current positions of the axis of the gantry (mm).
`MoveToPosition`	Move the axes of the gantry to the desired positions (mm) at the requested speeds (mm/sec).
`GetLengths`	Get the lengths of the axes of the gantry (mm).
`Home`	Run the homing sequence of the gantry to re-calibrate the axes with respect to the limit switches.
`GetGeometries`	Get all the geometries associated with the gantry in its current configuration, in the frame of the gantry.
`IsMoving`	Get if the gantry is currently moving.
`Stop`	Stop all motion of the gantry.
`Reconfigure`	Reconfigure this resource.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`GetResourceName`	Get the `ResourceName` for this gantry with the given name.
`Close`	Safely 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.

API key and API key ID

By default, the sample code does not include your machine API key and API key ID. We strongly recommend that you add your API key and API key ID as an environment variable and import this variable into your development environment as needed.

To show your machine’s API key and API key ID in the sample code, toggle Include API key on the CONNECT tab’s Code sample page.

Caution

Do not share your API key or machine address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your machine, or to the computer running your machine.

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:

Python
Go

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:

extra Map<String, dynamic>? (optional)

Returns:

Future<List<double>>

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:

positions List<double> (required)
speeds List<double> (required)
extra Map<String, dynamic>? (optional)

Returns:

Future<void>

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:

extra Map<String, dynamic>? (optional)

Returns:

Future<List<double>>

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:

extra Map<String, dynamic>? (optional)

Returns:

Future<bool>

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.

Python

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[viam.proto.common.Geometry]): The geometries associated with the Component.

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:

Future<bool>

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:

extra Map<String, dynamic>? (optional)

Returns:

Future<void>

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:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

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:

command Map<String, dynamic> (required)

Returns:

Future<Map<String, dynamic>>

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.

Python
Flutter

Parameters:

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

Returns:

(viam.proto.common.ResourceName): The ResourceName of this Resource.

Example:

my_gantry_name = Gantry.get_resource_name("my_gantry")

For more information, see the Python SDK Docs.

Parameters:

name String (required)

Returns:

ResourceName

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python
Go

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.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!