# gpio

The `gpio` model supports [DC motors](https://en.wikipedia.org/wiki/DC_motor) (both brushed and brushless).

Technically, you must choose a motor model based on the motor driver, not the motor itself. The `gpio` model supports a DC or BLDC motor if it is wired to a motor driver that is controlled by general-purpose input/output (GPIO) pins on a board component. If your motor driver uses a different communication protocol such as I2C or SPI, you should use a different motor model. If you have a stepper motor, use a compatible stepper-specific model such as [`gpiostepper`](https://docs.viam.com/reference/components/motor/gpiostepper/).

#### Note

[Encoders](https://docs.viam.com/reference/components/encoder/) can be configured to work with `gpio` motors. Find more information in the [encoded motor documentation](https://docs.viam.com/reference/components/motor/encoded-motor/).

To configure a DC motor as a component of your machine, first make sure the motor is wired to a suitable motor driver, which is in turn wired to a board. Configure the [board](https://docs.viam.com/reference/components/board/) to which the motor driver is wired.

- [JSON Template](https://docs.viam.com/reference/components/motor/gpio/#gpio-config-0)
- [JSON Example](https://docs.viam.com/reference/components/motor/gpio/#gpio-config-1)

```json
{
  "components": [
    {
      "name": "<your-board-name>",
      "model": "<your-board-model>",
      "api": "rdk:component:board",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "<your-motor-name>",
      "model": "gpio",
      "api": "rdk:component:motor",
      "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:

```json
{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "api": "rdk:component:board",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "example-gpio",
      "model": "gpio",
      "api": "rdk:component:motor",
      "attributes": {
        "pins": {
          "dir": "36",
          "pwm": "32"
        },
        "board": "local",
        "max_rpm": 500
      },
      "depends_on": []
    }
  ]
}
```

The following attributes are available for `gpio` motors:

| Name            | Type    | Required?  | Description |
|-----------------|---------|------------|-------------|
| `board`         | string  | **Required** | `name` of the [board](https://docs.viam.com/reference/components/board/) to which the motor driver is wired. |
| `max_rpm`      | int     | **Required** | This is an estimate of the maximum RPM the motor will run at with full power under no load. The [`GoFor`](https://docs.viam.com/reference/apis/components/motor/#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](https://docs.viam.com/reference/components/motor/encoded-motor/)`gpio` motors._ |
| `pins`          | object  | **Required** | A structure that holds pin configuration information; [see below](https://docs.viam.com/reference/components/motor/gpio/#pins). |
| `min_power_pct` | float   | Optional    | Sets a limit on minimum power percentage sent to the motor.<br>Default: `0.0` |
| `max_power_pct` | float   | Optional    | Range is 0.06 to 1.0; sets a limit on maximum power percentage sent to the motor.<br>Default: `1.0` |
| `pwm_freq`     | int     | Optional    | Sets the PWM pulse frequency in Hz. Many motors operate optimally in the kHz range.<br>Default: `800` |
| `dir_flip`     | bool    | Optional    | Flips the direction of “forward” versus “backward” rotation. Default: `false` |
| `encoder`      | string  | Optional    | The name of an encoder attached to this motor. See [encoded motor](https://docs.viam.com/reference/components/motor/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)](https://en.wikipedia.org/wiki/Pulse-width_modulation) 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:

| Name | Type | Required? | Description |
| --- | --- | --- | --- |
| `a` | string | **Required** for some drivers | Board pin number this motor driver’s “IN1” or “A” pin is wired to. |
| `b` | string | **Required** for some drivers | Board pin number this motor driver’s “IN2” or “B” pin is wired to. |
| `dir` | string | **Required** for some drivers | Board pin number this motor driver’s direction (“DIR”) pin is wired to. |
| `pwm` | string | **Required** for some drivers | Board pin number this motor driver’s “PWM” pin is wired to. |
| `en_high` / `en_low` | string | Optional | Some 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`. |

#### Important

Only two or three of these `pins` attributes are required, depending on your motor driver.

If your motor drivers uses only In1 and In2, and not a third PWM pin, **do not configure a `pwm` pin**.

## Wiring examples

#### Tip

The following are just examples and do not apply to all motor setups. Refer to your motor and motor driver data sheets for information on power requirements and how to properly wire your motor.

### Brushed DC motor

Taking a 12V brushed DC motor controlled by a [DRV8256E Single Brushed DC Motor Driver Carrier](https://www.pololu.com/product/4038) wired to a Raspberry Pi as an example, the wiring diagram would look like this:

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](https://pinout.xyz/) 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.