Configure a GPIO-Controlled Motor

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

Encoders can be configured 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>",
          "en_low": "<int>"
        },
        "board": "<your-board-name>",
        "max_rpm": <int>,
        "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",
        "max_rpm": 500
      },
      "depends_on": []
    }
  ]
}

Same example JSON as on the JSON example tab, with notes alongside it. See attribute table below for all the same information.

The following attributes are available for gpio motors:

NameTypeInclusionDescription
boardstringRequiredname of the board to which the motor driver is wired.
max_rpmintRequiredThis is an estimate of the maximum RPM the motor will run at with full power under no load. The GoFor method calculates how much power to send to the motor as a percentage of max_rpm. If unknown, you can set it to 100, which will mean that giving 40 as the rpm argument to GoFor or GoTo will set it to 40% speed. Not required or available for encoded gpio motors.
pinsobjectRequiredA structure that holds pin configuration information; see below.
min_power_pctfloatOptionalSets a limit on minimum power percentage sent to the motor.
Default: 0.0
max_power_pctfloatOptionalRange 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, in addition to "en_high" or "en_low", 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.
pwmstringRequired for some driversBoard pin number this motor driver’s “PWM” pin is wired to.
en_high / en_lowstringOptionalSome drivers have optional enable pins that enable or disable the driver chip. If your chip requires a high signal to be enabled, add en_high with the pin number to this struct. If you need a low signal use en_low.

Wiring examples

Brushed DC motor

Taking a 12V brushed DC motor controlled by a DRV8256E Single Brushed DC Motor Driver Carrier wired to a Raspberry Pi as an example, the wiring diagram would look like this:

An example wiring diagram showing a Raspberry Pi, 12V power supply, DRV8256E motor driver, and 12V brushed DC motor. The logic side of the driver is connected to the Pi’s ground and 3.3V pins. The driver pin for PWM goes to pin 32 on the Pi and the direction pin goes to pin 36 on the Pi. The motor side of the motor driver is connected to the ground and 12V terminals of a power supply and the OUT1 and OUT2 pins go to the two terminals of the motor.

The signal wires in the diagram run from two GPIO pins on the Pi to the DIR and PWM pins on the motor driver. Refer to a Raspberry Pi pinout schematic to locate generic GPIO pins and determine their pin numbers for configuration.

Brushless DC motor

Brushless DC motor drivers work in much the same way as brushed DC motor drivers. They typically require a PWM/DIR input or an A/B (In1/In2) and PWM input to set the motor power and direction. The key difference between a brushed and brushless motor driver is on the motor output side. Brushless motors typically have three power connections (commonly referred to as A, B and C; or sometimes Phase 1, 2 and 3) and 3 sensor connections (commonly referred to as Hall A, Hall B, and Hall C) running between the motor and driver.

The configuration file of a BLDC motor with Viam is the same as that of a brushed motor. Only the output side of the driver board is different in that more wires connect the driver to the motor.

An example wiring diagram showing a Raspberry Pi, 12V power supply, RioRand 400W brushless DC motor controller, and 3 phase 12V brushless DC motor. The motor has three power wires (one for each phase) and five sensor wires (two to power the sensor and one for each of the three Hall effect sensors).

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.