Configure a GPIO/ADC-Based Input Controller

Configure a gpio input controller to use a GPIO- or ADC-based device to communicate with 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 input_controller type, then select the gpio model. Enter a name or use the suggested name for your input controller and click Create.

An example configuration for a GPIO input controller component in the Viam App config builder

Click {} (Switch to advanced) to edit buttons and axes. Copy and paste the following attribute template into your input controller’s Attributes box. Then remove and fill in the attributes as applicable to your input controller, according to the table below.

{
  "board": "<your-board-name>",
  "buttons": {
    "<your-button-name>": {
      "control": "<button-control-name>",
      "invert": <boolean>,
      "debounce_msec": <int>
    }
  },
  "axes": {
    "<your-axis-name>": {
      "control": "<axis-control-name>",
      "min": <int>,
      "max": <int>,
      "poll_hz": <int>,
      "deadzone": <int>,
      "min_change": <int>,
      "bidirectional": <boolean>,
      "invert": <boolean>
    }
  },
  "depends_on": ["<your-board-name>"]
}

You can also select board in the builder editing mode to clarify the board you want to configure with this input controller.

{
  "board": "piboard",
  "buttons": {
    "interrupt1": {
      "control": "ButtonNorth",
      "invert": false,
      "debounce_msec": 5
    },
    "interrupt2": {
      "control": "ButtonSouth",
      "invert": true,
      "debounce_msec": 5
    }
  },
  "axes": {
    "analog1": {
      "control": "AbsoluteX",
      "min": 0,
      "max": 1023,
      "poll_hz": 50,
      "deadzone": 30,
      "min_change": 5,
      "bidirectional": false,
      "invert": false
    },
    "analog2": {
      "control": "AbsoluteY",
      "min": 0,
      "max": 1023,
      "poll_hz": 50,
      "deadzone": 30,
      "min_change": 5,
      "bidirectional": true,
      "invert": true
    }
  },
  "depends_on": ["piboard"]
}

{
  "components": [
    {
      "name": "<your-gpio-input-controller-name>",
      "model": "gpio",
      "type": "input_controller",
      "namespace": "rdk",
      "attributes": {
        "board": "<your-board-name>",
        "buttons": {
          "<your-button-name>": {
            "control": "<button-control-name>",
            "invert": <boolean>,
            "debounce_msec": <int>
          }
        },
        "axes": {
          "<your-axis-name>": {
            "control": "<axis-control-name>",
            "min": <int>,
            "max": <int>,
            "poll_hz": <int>,
            "deadzone": <int>,
            "min_change": <int>,
            "bidirectional": <boolean>,
            "invert": <boolean>
          }
        }
      },
      "depends_on": ["<your-board-name>"]
    }
  ]
}

{
  "components": [
    {
      "name": "my_gpio_ic",
      "model": "gpio",
      "type": "input_controller",
      "namespace": "rdk",
      "attributes": {
        "board": "piboard",
        "buttons": {
          "interrupt1": {
            "control": "ButtonNorth",
            "invert": false,
            "debounce_msec": 5
          },
          "interrupt2": {
            "control": "ButtonSouth",
            "invert": true,
            "debounce_msec": 5
          }
        },
        "axes": {
          "analog1": {
            "control": "AbsoluteX",
            "min": 0,
            "max": 1023,
            "poll_hz": 50,
            "deadzone": 30,
            "min_change": 5,
            "bidirectional": false,
            "invert": false
          },
          "analog2": {
            "control": "AbsoluteY",
            "min": 0,
            "max": 1023,
            "poll_hz": 50,
            "deadzone": 30,
            "min_change": 5,
            "bidirectional": true,
            "invert": true
          }
        }
      },
      "depends_on": ["piboard"]
    }
  ]
}

The following attributes are available for gpio input controllers:

NameTypeRequired?Description
boardstringRequiredThe name of the board component with GPIO or ADC pins to use as the controlling device.
buttonsobjectRequiredThe Buttons available for control. These should be connected to the GPIO/ADC board.

Each button has the following fields:
  • name: Name of the Digital Interrupt the button/switch is connected to, as configured on the board component.
  • control: The Control type to use when reporting events as this button’s state is changed.
  • invert: Boolean indicating if the digital input (high/low) should be inverted when reporting button Control value indicating button state.
    This option is given because digital switches vary between high, 1, and low, 0, as their default at rest.
    • true: 0 is pressed, and 1 is released.
    • false (default): 0 is released, and 1 is pressed.
  • debounce_ms: How many milliseconds to wait for the interrupt to settle. This is needed because some switches can be electrically noisy.
axesobjectRequiredThe Axes available for control. These should be connected to the GPIO/ADC board.

Each axis has the following fields:
  • name: Name of the Analog Reader that reports ADC values for the axis Control, as configured on the board component.
  • control: The Control type to use when reporting events as this axis’s position is changed.
  • min: The minimum ADC value that the analog reader can report as this axis’s position changes.
  • max: The maximum ADC value that the analog reader can report as this axis’s position changes.
  • deadzone: The absolute ADC value change from the neutral 0 point to still consider as a neutral position. This option is given so tiny wiggles on loose controls don’t result in events being reported.
  • min_change: The minimum absolute ADC value change from the previous ADC value reading that can occur before reporting a new PositionChangeAbs Event. This option is given so tiny wiggles on loose controls don’t result in events being reported.
  • bidirectional: Boolean indicating if the axis changes position in 1 direction, like on an analog trigger or pedal, or 2, like on an analog control stick.
    • true: The axis should report center, 0, as halfway between the min/max ADC values.
    • false: 0 is still the neutral point of the axis, but only positive change values can be reported.
  • poll_hz: How many times per second to check for a new ADC reading that can generate an event.
  • invert: Boolean indicating if the direction of the axis should be flipped when translating ADC value readings to the axis Control value indicating position change.
    • true: flips the direction of the axis so that the minimum ADC value is reported as the maximum axis Control value.
    • false: keeps the direction of the axis the same, so that the minimum ADC value is reported as the minimum axis Control value.

Test the input controller

After you configure your input controller, open the input controller’s TEST panel on the CONFIGURE or CONTROL tabs. View the current value of each input on your controller.

The input controller component in the test panel of the Viam app.

Troubleshooting

You can find additional assistance in the Troubleshooting section.

You can also ask questions in the Community Discord and we will be happy to help.

Next steps

For more configuration and development info, see:

Input controller API

Give commands to register callbacks for events, allowing you to use input devices to control your machines.

Configure a smart machine

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

Drive a Rover with a Gamepad

Drive a wheeled rover with a Bluetooth gamepad that has a dongle.

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.