Configure a Single Encoder

A single encoder sends a signal from the rotating encoder over a single wire to one pin on the board. The direction of spin is dictated by the motor that has this encoder’s name in its encoder attribute field.

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

Configuration of a single encoder in the Viam app config builder.

Fill in and edit the attributes as applicable.

  "name": "<your-encoder-name>",
  "model": "single",
  "type": "encoder",
  "namespace": "rdk",
  "attributes": {
    "board": "<your-board-name>",
    "pins": {
      "i": "<your-pin-number-on-board>"

The following attributes are available for single encoders:

boardstringRequiredThe name of the board to which the encoder is wired.
pinsobjectRequiredA struct holding the name of the pin wired to the encoder:
  • i: Pin number of the pin to which the encoder is wired.

Viam also supports a model of encoder called "incremental" which uses two pins.

Test the encoder

Once your encoder is configured and connected, go to the CONTROL tab and click on the encoder’s dropdown 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 machine’s LOGS tab for errors, and review the configuration.

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.