Configure an incremental encoder

Use the incremental encoder model to configure a quadrature encoder.

Configuring an incremental encoder requires specifying the pin numbers of the two pins on the board to which the encoder is wired. These two pins provide the phase outputs used to measure the speed and direction of rotation in relation to a given reference point.

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 encoder type, then select the incremental model. Enter a name for your encoder and click Create.

Configuration of an incremental encoder in the Viam app config builder.

Fill in and edit the attributes as applicable.

{
  "name": "<your-encoder-name>",
  "type": "encoder",
  "model": "incremental",
  "attributes": {
    "board": "<your-board-name>",
    "pins": {
      "a": "<your-first-pin-number>",
      "b": "<your-second-pin-number>"
    }
  }
}

{
  "components": [
    {
      "name": "local",
      "type": "board",
      "model": "pi",
      "attributes": {}
    },
    {
      "name": "myEncoder",
      "type": "encoder",
      "model": "incremental",
      "attributes": {
        "board": "local",
        "pins": {
          "a": "13",
          "b": "11"
        }
      }
    }
  ]
}

The following attributes are available for incremental encoders:

NameTypeInclusionDescription
boardstringRequiredThe name of the board to which the encoder is wired.
pinsobjectRequiredA struct holding the names of the pins wired to the encoder:
  • a: Pin number of one of the pins to which the encoder is wired.
  • b: Required for two phase encoder. Pin number for the second board pin to which the encoder is wired.

Viam also supports a model of encoder called "single" which requires only one pin (i).

Test the encoder

Once your encoder is configured and connected, go to the Control tab and click on the encoder’s drop-down panel. The ticks count is displayed. Try moving the encoder (for example, by turning a motor it is attached to) and check whether the count increases as expected.

Encoder control panel.

If the encoder does not appear on the Control tab, or if you notice unexpected behavior, check your robot’s Logs tab for errors, and review the configuration.



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