Edit

Configure a GPIO-Controlled Servo

Configure a gpio servo to integrate a hobby servo controlled by general-purpose input/output (GPIO) pins on a non-viam:raspberry-pi:rpi model board into your machine. Physically connect your servo to your board and power both on. Then, configure the servo:

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 servo type, then select the gpio model. Enter a name or use the suggested name for your servo and click Create.

An example configuration for a gpio servo in the Viam app Config Builder.

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

{
  "components": [
    {
      "name": "<your-servo-name>",
      "model": "gpio",
      "type": "servo",
      "namespace": "rdk",
      "attributes": {
        "pin": "<your-pin-number>",
        "board": "<your-board-name>",
        "min_angle_deg": <float>,
        "max_angle_deg": <float>,
        "starting_position_deg": <float>,
        "frequency_hz": <int>,
        "pwm_resolution": <int>,
        "min_width_us": <int>,
        "max_width_us": <int>
      }
    }
  }

{
  "components": [
    {
      "name": "local",
      "model": "jetson",
      "type": "board",
      "namespace": "rdk"
    },
    {
      "name": "my_servo",
      "model": "gpio",
      "type": "servo",
      "namespace": "rdk",
      "attributes": {
        "pin": "16",
        "board": "local"
      }
    }
  ]
}

The following attributes are available for gpio servos:

Name	Type	Required?	Description
`pin`	string	Required	The pin number of the pin the servo’s control wire is wired to on the board.
`board`	string	Required	`name` of the board the servo is wired to.
`min_angle_deg`	float	Optional	The minimum angle in degrees that the servo can reach. Default = `0.0` Range = [`0.0`, `180.0`]
`max_angle_deg`	float	Optional	The maximum angle in degrees that the servo can reach. Default = `180.0` Range = [`0.0`, `180.0`]
`starting_position_deg`	float	Optional	Starting position of the servo in degrees. Default = `0.0` Range = [`0.0`, `180.0`]
`frequency_hz`	int	Optional	The frequency of PWM pulses sent to the servo, in Hertz (Hz). Default = [`300`] Range = [`0`, `450`]
`pwm_resolution`	int	Optional	The resolution of the PWM driver (for example, the number of ticks for a full period). If not specified or given as `0`, the driver will attempt to estimate the resolution.
`min_width_us`	int	Optional	Override the safe minimum PWM pulse width in microseconds. Range > `450`
`max_width_us`	int	Optional	Override the safe maximum PWM pulse width in microseconds. Range < `2500`

Tip

Refer to your servo’s data sheet for pulse-width modulation (PWM), rotation, and wiring specifications.

Test the servo

After you establish the connection to your servo motor, open the servo’s TEST panel on the CONFIGURE or CONTROL tabs. Use the buttons to move the servo motor to the desired angle.

Troubleshooting

If your servo is not working as expected, follow these steps:

Check your machine logs on the LOGS tab to check for errors.
Review this servo model’s documentation to ensure you have configured all required attributes.
Check that all wires are securely attached to the correct pins on the board.
Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the servo there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.

Next steps

For general configuration and development info, see:

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!