Encoder Component

An encoder is a device that is used to sense angular position, direction and/or speed of rotation. It is often used in conjunction with a motor, and is sometimes even built into a motor. An encoder could also be positioned on a passive joint or other rotational object to keep track of the joint angle.

Hardware Requirements

• A board (like a Raspberry Pi)
• An encoder (quadrature or single phase)
• Some sort of rotary robot part (like a motor, joint or dial) for which you want to measure movement

Mechanism

Viam supports quadrature encoders¹, which output two phases that can be used together to detect how far something has turned and in which direction. Each phase output goes to a different pin on the board. Viam also supports single pin “pulse output” encoders which give relative position but not direction.

In either case position can only be determined relative to the starting position; these encoders are incremental and do not indicate absolute position. Absolute encoders are another type of hardware that is not natively supported in Viam as of August 19th, 2022.

Viam Configuration

Configuring an encoder requires configuring two pins on the board to which the encoder is wired, as well as configuring the board component. In the case of an encoded motor, the motor must be configured as well, per the motor component topic.

Required Attributes

Besides type (“encoder”), model (“incremental” for a two phase encoder) and name (of your choosing), encoder requires the following:

The pins struct contains:

Viam also supports a model of encoder called “single” that requires only one pin (i). However, the incremental model is recommended as encoders with two signal wires are more accurate.

Example Config

The following example shows the configuration of a board and an encoder.

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