# Switch API

The switch API allows you to give commands to your [switch components](https://docs.viam.com/reference/components/switch/) for reading the state of a physical switch that has multiple discrete positions. A simple switch has two positions, and a knob could have any number of positions.

The switch component supports the following methods:

| Method Name | Description | `viam-micro-server` Support |
| --- | --- | --- |
| [`SetPosition`](https://docs.viam.com/reference/apis/components/switch/#setposition) | Set the position of the switch. |  |
| [`GetPosition`](https://docs.viam.com/reference/apis/components/switch/#getposition) | Return the current position of the switch. |  |
| [`GetNumberOfPositions`](https://docs.viam.com/reference/apis/components/switch/#getnumberofpositions) | Return the number of valid positions for this switch. |  |
| [`DoCommand`](https://docs.viam.com/reference/apis/components/switch/#docommand) | Execute model-specific commands that are not otherwise defined by the component API. |  |
| [`GetResourceName`](https://docs.viam.com/reference/apis/components/switch/#getresourcename) | Get the `ResourceName` for this servo. |  |
| [`Close`](https://docs.viam.com/reference/apis/components/switch/#close) | Safely shut down the resource and prevent further use. |  |

## API

### SetPosition

Set the position of the switch. Position must be within the valid range for the switch type. Supported by `viam-micro-server`.

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

**Parameters:**

- `position` ( [int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (required): The position of the switch within the range of available positions.
- `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/switch/client/index.html#viam.components.switch.client.SwitchClient.set_position).

### GetPosition

Return the current position of the switch. Supported by `viam-micro-server`.

- [Python](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-2-0)
- [Go](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-2-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-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:**

- ( [int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)): : The current position of the switch within the range of available positions.

**Example:**

```python

```

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

### GetNumberOfPositions

Return the number of valid positions for this switch. Supported by `viam-micro-server`.

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

**Parameters:**

**Returns:**

- (Tuple[ [int](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex), Sequence[ [str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str) ]]): : The number of available positions and their labels.

**Example:**

```python

```

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

### 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 switch 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/switch/#tabset-referenceapiscomponentsswitch-4-0)
- [Go](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-4-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-4-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/switch/client/index.html#viam.components.switch.client.SwitchClient.do_command).

### GetResourceName

Get the `ResourceName` for this servo.

- [Python](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-5-0)
- [Go](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-5-1)
- [TypeScript](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-5-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/switch/client/index.html#viam.components.switch.client.SwitchClient.get_resource_name).

### Close

Safely shut down the resource and prevent further use.

- [Python](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-6-0)
- [Go](https://docs.viam.com/reference/apis/components/switch/#tabset-referenceapiscomponentsswitch-6-1)

**Parameters:**

- None.

**Returns:**

- None.

**Example:**

```python

```