Configure a GPIO Motor (Micro-RDK)

The gpio model supports DC motors (both brushed and brushless).

You can configure encoders to work with gpio motors. Find more information in the encoded motor documentation.

To configure a DC motor as a component of your machine, first configure the board to which the motor driver is wired. Then add your 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 gpio model. Enter a name for your motor and click Create.

G P I O motor config in the builder UI with the In1 and In2 pins configured and the PWM pin field left blank.

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": "gpio",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "pins": {
          "dir": "<int>",
          "pwm": "<int>"
        },
        "board": "<your-board-name>",
        "min_power_pct": <float>,
        "max_power_pct": <float>,
        "pwm_freq": <float>,
        "dir_flip": <float>
      },
      "depends_on": []
    }
  ]
}

An example configuration for a gpio motor:

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "example-gpio",
      "model": "gpio",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "pins": {
          "dir": "36",
          "pwm": "32"
        },
        "board": "local"
      },
      "depends_on": []
    }
  ]
}

The following attributes are available for gpio motors:

NameTypeInclusionDescription
boardstringRequiredname of the board to which the motor driver is wired.
pinsobjectRequiredA structure that holds pin configuration information; see below.
min_power_pctnumberOptionalSets a limit on minimum power percentage sent to the motor.
Default: 0.0
max_power_pctnumberOptionalRange is 0.06 to 1.0; sets a limit on maximum power percentage sent to the motor.
Default: 1.0
pwm_freqintOptionalSets the PWM pulse frequency in Hz. Many motors operate optimally in the kHz range.
Default: 800
dir_flipboolOptionalFlips the direction of “forward” versus “backward” rotation. Default: false
encoderstringOptionalThe name of an encoder attached to this motor. See encoded motor.

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

pins

There are three common ways for your computer to communicate with a brushed DC motor driver chip. Your motor driver data sheet will specify which one to use.

  • PWM/DIR: Use this if one of your motor driver’s pins (labeled “PWM”) takes a pulse width modulation (PWM) signal to the driver to control speed while another pin labeled “DIR” takes a high or low signal to control the direction.
    • Configure pwm and dir.
  • In1/In2: Use this if your motor driver has pins labeled “IN1” and “IN2” or “A” and “B,” or similar. One digital signal set to a high voltage and another set to a low voltage turns the motor in one direction and vice versa. Speed is controlled with PWM through one or both pins.
    • Configure a and b.
  • In1/In2 and PWM: Use this if your motor driver uses three pins: In1 (A) and In2 (B) to control direction and a separate PWM pin to control speed.
    • Configure a, b, and pwm.

Inside the pins struct you need to configure two or three of the following depending on your motor driver:

NameTypeInclusionDescription
astringRequired for some driversBoard pin number this motor driver’s “IN1” or “A” pin is wired to.
bstringRequired for some driversBoard pin number this motor driver’s “IN2” or “B” pin is wired to.
dirstringRequired for some driversBoard pin number this motor driver’s direction (“DIR”) pin is wired to.
pwmstringRequiredBoard pin number this motor driver’s “PWM” pin is wired to.

PWM frequency and esp32 boards

Each gpio motor uses a PWM pin at 10000 Hz PWM frequency.

This leaves you with three remaining PWM frequencies for use on an esp32. If the frequency of another PWM signal is unimportant, it can also be set to 10000 Hz. See PWM signals on esp32 pins for more information.

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.