Configure a GPIO-Controlled Stepper Motor

The gpiostepper model of the motor component supports bipolar stepper motors controlled by basic stepper driver chips (such as DRV8825, A4988, or TMC2209) that take step and direction input through GPIO and move the motor one step per pulse.

To configure a gpiostepper motor as a component of your machine, first configure the board to which the motor driver is wired. Then, add the motor:

Navigate to the Config tab of your machine’s page in the Viam app. Click on the Components subtab and click Create component. Select the motor type, then select the gpiostepper model. Enter a name for your motor and click Create.

Screenshot of a gpiostepper motor config with the step and dir pins configured to pins 13 and 15.

Edit and fill in the attributes as applicable.

{
  "components": [
    {
      "name": "<your-board-name>",
      "model": "<your-board-model>",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": [],
    },
    {
      "name": "<your-motor-name>",
      "model": "gpiostepper",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "board": "<your-board-name>",
        "pins": {
          "step": "<pin-number>",
          "dir": "<pin-number>"
        },
        "ticks_per_rotation": <int>,
        "stepper_delay": <int>
      },
      "depends_on": []
    }
  ]
}

Here’s an example of a basic stepper driver config:

{
  "components": [
    {
      "name": "example-board",
      "model": "pi",
      "type": "board",
      "namespace": "rdk"
    },
    {
      "name": "example-motor",
      "model": "gpiostepper",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "board": "example-board",
        "pins": {
          "step": "13",
          "dir": "15"
        },
        "ticks_per_rotation": 200
      }
    }
  ]
}

motor-gpiostepper-json.

The following attributes are available for gpiostepper motors:

NameTypeInclusionDescription
boardstringRequiredname of the board the motor driver is wired to.
pinsobjectRequiredA struct containing the board pin numbers that the step and dir pins of the motor driver are wired to.
ticks_per_rotationintRequiredNumber of full steps in a rotation. 200 (equivalent to 1.8 degrees per step) is very common. If your data sheet specifies this in terms of degrees per step, divide 360 by that number to get ticks per rotation.
stepper_delayintOptionalTime in microseconds to remain high for each step.

Refer to your motor and motor driver data sheets for specifics.

Wiring example

Typically, a stepper motor will have an even number of wires. Each pair of wires forms a loop through a coil of the motor. In the case of a four wire (bi-polar) stepper, one pair of wires may be labeled A1 and A2 and the other B1 and B2. Refer to your motor data sheet and motor driver data sheet for correct wiring.

The following example uses a Big Tree Tech breakout board with a TMC2209 integrated circuit to drive a two phase stepper motor.

An example wiring diagram for a four wire Nema 17 stepper motor driven by a Big Tree Tech TMC2209 stepper driver. The driver is connected to a Raspberry Pi with step and dir pins, as well as logic power wires. A separate 12V power supply is attached to the motor driver to power the motor.

In this particular example the enable pin on the upper left corner of the driver is connected to ground to pull it low. See the data sheet of your stepper motor and stepper motor driver for information on how to wire your specific hardware.

Test the motor

Once your motor is configured and connected, go to the Control tab and click on the motor’s dropdown panel. Use the buttons to try turning your motor forwards or backwards at different power levels and check whether it moves as expected.

Motor control panel.

If the motor 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.