Configure a GPIO/ADC based input controller

Configuring a gpio input controller allows you to use a GPIO or ADC based device to communicate with your robot.

Configuration

Refer to the following example configuration for an input controller of model gpio with a GPIO based device serving as the board component.

Be aware that complete configuration is not visible in the “Config Builder” tab:

Navigate to the Config tab of your robot’s page in the Viam app. Click on the Components subtab and click Create component. Select the input_controller type, then select the gpio model. Enter a name for your input controller and click Create.

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

Edit and fill in the attributes as applicable.

{
    "components": [
    {
      "name": "<your-gpio-input-controller-name>",
      "type": "input_controller",
      "model": "gpio",
      "attributes": {
        "board": "<your-board-name>",
        "buttons": {
          "<your-button-name>": {
            "control": "<button-control-name>",
            "invert": <boolean>,
            "debounce_msec": <#>
          }
        },
        "axes": {
          "<nyour-axis-name>": {
            "control": "<axis-control-name>",
            "min": <#>,
            "max": <#>,
            "poll_hz": <#>,
            "deadzone": <#>,
            "min_change": <#>,
            "bidirectional": <boolean>,
            "invert": <boolean>
          }
        }
      },
      "depends_on": [
        "<your-board-name>"
      ]
    }, ... // <INSERT ANY ADDITIONAL COMPONENT CONFIGURATION>
}

{
    "components": [
    {
      "name": "my_gpio_ic",
      "type": "input_controller",
      "model": "gpio",
      "attributes": {
        "board": "piboard",
        "buttons": {
          "interrupt1": {
            "control": "ButtonNorth",
            "invert": false,
            "debounce_msec": 5
          },
          "interrupt2": {
            "control": "ButtonSouth",
            "invert": true,
            "debounce_msec": 5
          }
        },
        "axes": {
          "analogReader1": {
            "control": "AbsoluteX",
            "min": 0,
            "max": 1023,
            "poll_hz": 50,
            "deadzone": 30,
            "min_change": 5,
            "bidirectional": false,
            "invert": false
          },
          "analogReader2": {
            "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:

NameTypeInclusionDescription
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.

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.



Have questions, or want to meet other people working on robots? Join our Community Discord.