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.
`GetKinematics`	Get the kinematics information associated with the gantry.
`GetResourceName`	Get the `ResourceName` for this gantry.
`Close`	Safely shut down the resource and prevent further use.

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=machine, 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.FromProvider(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 (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<number[]>): A list of the current position of each axis in millimeters.

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Get the current positions of the axes in millimeters
const positions = await gantry.getPosition();

For more information, see the TypeScript 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=machine, 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.FromProvider(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:

positionsMm (number) (required): The goal positions for each axis of the gantry.
speedsMmPerSec (number) (required): The desired speed for each axis to move to the respective position in positionsMm.
extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Create positions for a 3-axis gantry
const positions = [1, 2, 3];
const speeds = [3, 9, 12];

// Move the axes to the specified positions
await gantry.moveToPosition(positions, speeds);

For more information, see the TypeScript SDK Docs.

Parameters:

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

Returns:

Future

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=machine, 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.FromProvider(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 (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<number[]>): A list of the length of each axis in millimeters.

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Get the lengths of the axes in millimeters
const lengths = await gantry.getLengths();

For more information, see the TypeScript 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=machine, 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.FromProvider(machine, "my_gantry")

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

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise): A bool representing whether the gantry has run the homing sequence successfully.

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Run the homing sequence
const success = await gantry.home();

For more information, see the TypeScript 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
TypeScript

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:

my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
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.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise<commonApi.Geometry[]>)

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Get the geometries of this component
const geometries = await gantry.getGeometries();

For more information, see the TypeScript 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=machine, 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(await 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.FromProvider(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:

callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Check if the gantry is moving
const moving = await gantry.isMoving();
console.log('Moving:', moving);

For more information, see the TypeScript 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=machine, 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.FromProvider(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 (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

Example:

const gantry = new VIAM.GantryClient(machine, 'my_gantry');

// Stop all motion of the gantry
await gantry.stop();

For more information, see the TypeScript SDK Docs.

Parameters:

extra Map<String, dynamic>? (optional)

Returns:

Future

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. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own gantry and want to add features that have no corresponding built-in API method, you can implement 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:

my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
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.FromProvider(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 (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

Example:

// 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' } })
);

For more information, see the TypeScript 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.

GetKinematics

Get the kinematics information associated with the gantry.

Python
Go

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:

(viam.components.KinematicsReturn): : A tuple containing two values; the first [0] value represents the format of the file, either in URDF format (KinematicsFileFormat.KINEMATICS_FILE_FORMAT_URDF) or Viam’s kinematic parameter format (spatial vector algebra) (KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA), and the second [1] value represents the byte contents of the file. If available, a third [2] value provides meshes keyed by URDF filepath.

Example:

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

# Get the kinematics information associated with the gantry.
kinematics = await my_gantry.get_kinematics()

# Get the format of the kinematics file.
k_file = kinematics[0]

# Get the byte contents of the file.
k_bytes = kinematics[1]

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:

(referenceframe.Model): The kinematics model of the resource.
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

GetResourceName

Get the ResourceName for this gantry.

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:

None.

Returns:

(Name)

Example:

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

err = myGantry.Name()

For more information, see the Go SDK Docs.

Parameters:

None.

Returns:

(string): The name of the resource.

Example:

gantry.name

For more information, see the TypeScript SDK Docs.

Parameters:

name String (required)

Returns:

ResourceName

Example:

final myGantryResourceName = myGantry.getResourceName("my_gantry");

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:

my_gantry = Gantry.from_robot(robot=machine, name="my_gantry")
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.FromProvider(machine, "my_gantry")

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

For more information, see the Go SDK Docs.

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!