# Encoder API

The encoder API allows you to give commands to your [encoder components](https://docs.viam.com/hardware/common-components/add-an-encoder/) for getting the position of a motor or a joint in ticks or degrees.

The encoder component supports the following methods:

| Method Name | Description | `viam-micro-server` Support |
| --- | --- | --- |
| [`GetPosition`](https://docs.viam.com/reference/apis/components/encoder/#getposition) | Get the current position of the encoder in ticks or degrees. |  |
| [`ResetPosition`](https://docs.viam.com/reference/apis/components/encoder/#resetposition) | Set the current position of the encoder to be the new zero position. |  |
| [`GetProperties`](https://docs.viam.com/reference/apis/components/encoder/#getproperties) | Get a list of all the position types that are supported by a given encoder. |  |
| [`GetGeometries`](https://docs.viam.com/reference/apis/components/encoder/#getgeometries) | Get all the geometries associated with the encoder in its current configuration, in the frame of the encoder. |  |
| [`Reconfigure`](https://docs.viam.com/reference/apis/components/encoder/#reconfigure) | Reconfigure this resource. |  |
| [`DoCommand`](https://docs.viam.com/reference/apis/components/encoder/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. |  |
| [`GetResourceName`](https://docs.viam.com/reference/apis/components/encoder/#getresourcename) | Get the `ResourceName` for this encoder. |  |
| [`Close`](https://docs.viam.com/reference/apis/components/encoder/#close) | Safely shut down the resource and prevent further use. |  |

## API

### GetPosition

Get the current position of the encoder in ticks or degrees.
Relative encoders return ticks since last zeroing.
Absolute encoders return degrees.
Supported by `viam-micro-server`.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-1-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-1-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-1-2)

**Parameters:**

- `position_type` ( [viam.proto.component.encoder.PositionType.ValueType](https://python.viam.dev/autoapi/viam/gen/component/encoder/v1/encoder_pb2/index.html#viam.gen.component.encoder.v1.encoder_pb2.PositionType)) (optional): The desired output type of the position.
- `extra` (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any\]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- (Tuple\[ [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex), [PositionType.ValueType](https://python.viam.dev/autoapi/viam/gen/component/encoder/v1/encoder_pb2/index.html#viam.gen.component.encoder.v1.encoder_pb2.PositionType)\]): : A tuple containing two values; the first \[0\] the position of the encoder which can either be
ticks since last zeroing for a relative encoder or degrees for an absolute encoder, and the second \[1\] the type of
position the encoder returns (ticks or degrees).

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.get_position).

### ResetPosition

Set the current position of the encoder to be the new zero position.
Supported by `viam-micro-server`.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-2-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-2-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-2-2)

**Parameters:**

- `extra` (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), Any\]) (optional): Extra options to pass to the underlying RPC call.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- None.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.reset_position).

### GetProperties

Get a list of all the position types that are supported by a given encoder.
Supported by `viam-micro-server`.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-3-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-3-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-3-2)

**Parameters:**

**Returns:**

- ( [viam.components.encoder.encoder.Encoder.Properties](https://python.viam.dev/autoapi/viam/components/encoder/encoder/index.html#viam.components.encoder.encoder.Encoder.Properties)): : Map of position types to supported status.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.get_properties).

### GetGeometries

Get all the geometries associated with the encoder in its current configuration, in the [frame](https://docs.viam.com/reference/services/frame-system/) of the encoder.
The [motion](https://docs.viam.com/reference/services/motion/) and [navigation](https://docs.viam.com/reference/services/navigation/) services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-4-0)

**Parameters:**

**Returns:**

- ( [List\[viam.proto.common.Geometry\]](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.Geometry)): : The geometries associated with the Component.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.get_geometries).

### Reconfigure

Reconfigure this resource.
Reconfigure must reconfigure the resource atomically and in place.

- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-5-0)

**Parameters:**

- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
- `deps` [(Dependencies)](https://pkg.go.dev/go.viam.com/rdk/resource#Dependencies): The resource dependencies.
- `conf` [(Config)](https://pkg.go.dev/go.viam.com/rdk/resource#Config): The resource configuration.

**Returns:**

- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred.

For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource).

### DoCommand

Execute model-specific commands that are not otherwise defined by the component API.
Most models do not implement `DoCommand`.
Any available model-specific commands should be covered in the model’s documentation.
If you are implementing your own encoder as a modular resource and want to add features that have no corresponding built-in API method, you can implement them with [`DoCommand`](https://docs.viam.com/reference/sdks/docommand/).
Supported by `viam-micro-server`.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-6-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-6-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-6-2)

**Parameters:**

- `command` (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes\]) (required): The command to execute.
- `timeout` ( [float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

**Returns:**

- (Mapping\[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes\]): : Result of the executed command.

**Raises:**

- (NotImplementedError): Raised if the Resource does not support arbitrary commands.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.do_command).

### GetResourceName

Get the `ResourceName` for this encoder.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-7-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-7-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-7-2)

**Parameters:**

- `name` ( [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource.

**Returns:**

- ( [viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource.

**Example:**

```python

```

For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/components/encoder/client/index.html#viam.components.encoder.client.EncoderClient.get_resource_name).

### Close

Safely shut down the resource and prevent further use.

- [Python](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-8-0)
- [Go](https://docs.viam.com/reference/apis/components/encoder/#tabset-referenceapiscomponentsencoder-8-1)

**Parameters:**

- None.

**Returns:**

- None.

**Example:**

```python

```