Configure a Multi-Axis Gantry

Configure a multi-axis gantry to integrate a gantry made up of multiple single-axis gantries into your machine:

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 multi-axis model. Enter a name or use the suggested name for your gantry and click Create.

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

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

{
  "components": [
    ... // < INSERT YOUR MOTOR AND SINGLE-AXIS GANTRY CONFIGURATIONS >
    {
      "name": "<your-fake-gantry-name>",
      "model": "multi-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
          "subaxes_list": [
              "<xaxis-name>",
              "<yaxis-name>",
              "<zaxis-name>"
          ]
      },
      "depends_on": []
    }
  ]
}

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk"
    },
    {
      "name": "xmotor",
      "model": "gpiostepper",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "board": "local",
        "pins": {
          "dir": "11",
          "pwm": "13",
          "step": "15"
        },
        "stepperDelay": 50,
        "ticksPerRotation": 200
      }
    },
    {
      "name": "ymotor",
      "model": "gpiostepper",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "board": "local",
        "pins": {
          "dir": "16",
          "pwm": "18",
          "step": "22"
        },
        "stepperDelay": 50,
        "ticksPerRotation": 200
      }
    },
    {
      "name": "zmotor",
      "model": "gpiostepper",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "board": "local",
        "pins": {
          "dir": "29",
          "pwm": "31",
          "step": "33"
        },
        "stepperDelay": 50,
        "ticksPerRotation": 200
      }
    },
    {
      "name": "xaxis",
      "model": "single-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
        "length_mm": 1000,
        "board": "local",
        "limit_pin_enabled_high": false,
        "limit_pins": ["32", "36"],
        "motor": "xmotor",
        "gantry_rpm": 500,
        "axis": {
          "x": 1,
          "y": 0,
          "z": 0
        }
      }
    },
    {
      "name": "yaxis",
      "model": "single-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
        "length_mm": 1000,
        "board": "local",
        "limit_pin_enabled_high": false,
        "limit_pins": ["37", "38"],
        "motor": "ymotor",
        "gantry_rpm": 500,
        "axis": {
          "x": 0,
          "y": 1,
          "z": 0
        }
      }
    },
    {
      "name": "zaxis",
      "model": "single-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
        "length_mm": 1000,
        "board": "local",
        "limit_pin_enabled_high": false,
        "limit_pins": ["10", "12"],
        "motor": "zmotor",
        "gantry_rpm": 500,
        "axis": {
          "x": 0,
          "y": 0,
          "z": 1
        }
      },
      "frame": {
        "parent": "world",
        "orientation": {
          "type": "euler_angles",
          "value": {
            "roll": 0,
            "pitch": 40,
            "yaw": 0
          }
        },
        "translation": {
          "x": 0,
          "y": 3,
          "z": 0
        }
      }
    },
    {
      "name": "my_multi-axis_gantry",
      "model": "multi-axis",
      "type": "gantry",
      "namespace": "rdk",
      "attributes": {
        "subaxes_list": ["xaxis", "yaxis", "zaxis"],
        "move_simultaneously": "false"
      }
    }
  ]
}

The following attributes are available for multi-axis gantries:

AttributeTypeInclusionDescription
subaxes_listarrayRequiredAn array of the name of each of the sub-axes, the single-axis gantries that make up the multi-axis gantry.
move_simultaneouslybooleanOptionalA boolean indicating if the sub-axes should move together, or one at a time when MoveToPosition is called.
Default: false

Test the gantry

Once your gantry is configured and connected, go to the CONTROL tab and click on the gantry’s dropdown panel.

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

Gantry control panel.

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

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.