Encoder Component
The encoder component provides an API for getting the position of a motor or a joint in ticks or degrees.
If you have hardware or software that provides the position of a motor or joint, use an encoder component.
Encoder components are often used in conjunction with a motor, and are sometimes even built directly into motors. Encoders can also be mounted on a passive joint or other rotating object to keep track of the joint angle.
The encoder component supports:
- Incremental encoders, which can measure the speed and direction of rotation in relation to a given reference point like a starting point. These encoders output two phases. Based on the sequence and timing of these phases, it is determined how far something has turned and in which direction. Each phase output goes to a different pin on the board.
- Single phase or single pin “pulse output” encoders, which measure the position relative to the starting position but not the direction.
- Absolute encoders, which provide the absolute position of a rotating shaft, without requiring a reference point.
Configuration
To use an encoder, you need to add it to your machine’s configuration.
Go to your machine’s CONFIGURE page, and add a model that supports your encoder.
The following list shows the available encoder models. For additional configuration information, click on the model name:
Add support for other models
If none of the existing models fit your use case, you can create a modular resource to add support for it.
| Model | Description |
|---|---|
incremental | A two phase encoder, which can measure the speed and direction of rotation in relation to a given reference point |
single | A single pin “pulse output” encoder which returns its relative position but no direction |
Add support for other models
If none of the existing models fit your use case, you can create a modular resource to add support for it.
viam-micro-server works differently from the RDK, so creating modular resources for it is different.
Refer to the Micro-RDK Module Template on GitHub for information on how to create custom resources for your viam-micro-server machine.
You will need to recompile and flash your ESP32 yourself instead of using Viam’s prebuilt binary and installer.
API
The encoder API supports the following methods:
| Method Name | Description | viam-micro-server Support |
|---|---|---|
GetPosition | Get the current position of the encoder in ticks or degrees. | |
ResetPosition | Set the current position of the encoder to be the new zero position. | |
GetProperties | Get a list of all the position types that are supported by a given encoder. | |
GetGeometries | Get all the geometries associated with the encoder in its current configuration, in the frame of the encoder. | |
Reconfigure | Reconfigure this resource. | |
DoCommand | Execute model-specific commands that are not otherwise defined by the component API. | |
GetResourceName | Get the ResourceName for this encoder with the given name. | |
Close | Safely shut down the resource and prevent further use. |
Troubleshooting
If your encoder is not working as expected, follow these steps:
- Check your machine logs on the LOGS tab to check for errors.
- Review your encoder model’s documentation to ensure you have configured all required attributes.
- Check that all wires are securely attached to the correct pins.
- Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the encoder there.
If none of these steps work, reach out to us on the Community Discord and we will be happy to help.
Next steps
For general configuration, development, and usage info, see:
You can also use the encoder component with the following services:
- Data management service: To capture and sync the encoder’s data
- Motion service: To move machines or components of machines
- Navigation service: To navigate with GPS
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!