Configure a GPIO Servo (viam-micro-server)

Configure a gpio servo to integrate a hobby servo controlled by general-purpose input/output (GPIO) pins into your machine. Physically connect your servo to your microcontroller 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.

Copy and paste the following attribute template into your servo’s attributes field. Then remove and fill in the attributes as applicable to your servo, according to the table below.

{
  "pin": "<your-pin-number>",
  "board": "<your-board-name>",
  "frequency_hz": <int>,
  "min_angle_deg": <int>,
  "max_angle_deg": <int>,
  "min_period_us": <int>,
  "max_period_us": <int>,
  "pwm_resolution": <int>
}

{
  "pin": "16",
  "board": "local"
}

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

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

The following attributes are available for gpio servos:

NameTypeRequired?Description
pinstringRequiredThe GPIO number of the pin the servo’s control wire is wired to on the board.
boardstringRequiredname of the board the servo is wired to.
frequency_hzintOptionalThe frequency of PWM pulses sent to the servo, in Hertz (Hz).
Default = [300]
Range = [0, 450]
min_angle_degintOptionalThe minimum angle in degrees that the servo can reach.
Default = 0
Range = [0, 180]
max_angle_degintOptionalThe maximum angle in degrees that the servo can reach.
Default = 180
Range = [0, 180]
min_period_usintOptionalOverride the safe minimum PWM pulse width in microseconds.
Default: 500
max_period_usintOptionalOverride the safe maximum PWM pulse width in microseconds.
Default: 2500
pwm_resolutionintOptionalThe resolution of the PWM driver (for example, the number of ticks for a full period).
Default: 0

PWM frequency and esp32 boards

A gpio servo using a PWM pin 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 the same frequency as your servo. See PWM signals on esp32 pins for more information.

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.

The servo component in the test panel

Troubleshooting

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

  1. Check your machine logs on the LOGS tab to check for errors.
  2. Review this servo model’s documentation to ensure you have configured all required attributes.
  3. Check that all wires are securely attached to the correct pins on the board.
  4. 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:

Servo API

Commands for controlling the angular position of a servo precisely or getting its current status.

Configure a machine

Create a machine in a few steps using Viam's modular system of components and services without writing much or any code.

Write control code for your machine

Write code to control machines and run it on the machine or remotely.

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.