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-pi model board into your machine:

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:

NameTypeInclusionDescription
pinstringRequiredThe pin number of the pin the servo’s control wire is wired to on the board.
boardstringRequiredname of the board the servo is wired to.
min_angle_degfloatOptionalThe minimum angle in degrees that the servo can reach.
Default = 0.0
Range = [0.0, 180.0]
max_angle_degfloatOptionalThe maximum angle in degrees that the servo can reach.
Default = 180.0
Range = [0.0, 180.0]
starting_position_degfloatOptionalStarting position of the servo in degrees.
Default = 0.0
Range = [0.0, 180.0]
frequency_hzintOptionalThe frequency of PWM pulses sent to the servo, in Hertz (Hz).
Default = [300]
Range = [0, 450]
pwm_resolutionintOptionalThe 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_usintOptionalOverride the safe minimum PWM pulse width in microseconds.
Range > 450
max_width_usintOptionalOverride the safe maximum PWM pulse width in microseconds.
Range < 2500

Test the servo

After you establish the connection to your servo motor, navigate to the Control tab and select the dropdown panel dedicated to the motor. Use the buttons to move the servo motor to the desired angle.

The servo component in the control tab


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.