Configure a Single-Axis Gantry

Configure a single-axis gantry to integrate a single-axis gantry into your machine. Before configuring the gantry, configure any motor components that are part of the gantry.

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the gantry type, then select the single-axis model. Enter a name or use the suggested name for your sensor and click Create.

Creation of a single-axis gantry component in the Viam app config builder.

Fill in the attributes as applicable to your gantry, according to the table below.

{
  "components": [
    // < Your motor config >
    {
      "name": "<your-single-axis-gantry-name>",
      "model": "single-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
        "motor": "<your-motor-name>",
        "length_mm": <int>,
        "mm_per_rev": <int>
      },
      "depends_on": []
    }
  ]
}

The following attributes are available for single-axis gantries:

AttributeTypeRequired?Description
length_mmintRequiredLength of the axis of the gantry in millimeters.
motorstringRequiredname of the motor that moves the gantry’s actuator.
boardstringOptionalname of the board containing the limit switches and pins. If limit_pins exist, board is required.
limit_pinsobjectOptionalThe boards’s pins attached to the limit switches on either end. If the motor used does not include an encoder, limit_pins are required to be set.
limit_pin_enabled_highbooleanOptionalWhether the limit pins are enabled.
Default: false
mm_per_revintRequiredHow far the gantry moves (linear, distance in mm) per one revolution of the motor’s output shaft. This typically corresponds to Distance = PulleyDiameter * pi, or the pitch of a linear screw.
gantry_mm_per_secintOptionalThe speed at which the gantry moves in millimeters per second. Used to calculate the gantry motor’s revolutions per minute (RPM).
Default: 100 RPM

Test the gantry

Once your gantry is configured and connected, open the gantry’s TEST panel on the CONFIGURE or CONTROL tabs.

Use the panel to adjust the position of the actuator on the axis and check whether it moves as expected.

Gantry test panel.

If the gantry does not appear on the TEST panel, or if you notice unexpected behavior, check your machine’s LOGS tab for errors, and review the configuration.

Next steps

For more configuration and development info, see:

Gantry API

Give commands for coordinated control of one or more linear actuators.

Configure a smart machine

Create a machine in a few steps using Viam's modular system of components and services without writing much or any code.

Write control code for your machine

Write code to control machines and run it on the machine or remotely.

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.