Edit

Switch API

The switch API allows you to give commands to your switch components 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`	Set the position of the switch.
`GetPosition`	Return the current position of the switch.
`GetNumberOfPositions`	Return the number of valid positions for this switch.
`DoCommand`	Execute model-specific commands that are not otherwise defined by the component API.
`Close`	Safely shut down the resource and prevent further use.

Establish a connection

To get started using Viam’s SDKs to connect to and control your switch and the rest of your machine, go to your machine’s page on the Viam app, Navigate to the CONNECT tab’s Code sample page, select your preferred programming language, and copy the sample code.

To show your machine’s API key in the sample code, toggle Include API key.

Caution: Keep your API key and machine address safe

We strongly recommend that you add your API key and machine address as an environment variable. Anyone with these secrets can access your machine, and the computer running your machine.

When executed, this sample code creates a connection to your machine as a client.

The following examples assume you have an switch called "my_switch" configured as a component of your machine. If your switch has a different name, change the name in the code.

Import the switch package for the SDK you are using:

import (
  "go.viam.com/rdk/components/switch"
)

API

SetPosition

Set the position of the switch. Position must be within the valid range for the switch type.

Parameters:

position (int) (required): The position of the switch within the range of available positions.
extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (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:

my_switch = Switch.from_robot(robot=machine, name="my_switch")

# Update the switch from its current position to the desired position of 1.
await my_switch.set_position(1)

# Update the switch from its current position to the desired position of 0.
await my_switch.set_position(0)

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
position (uint32)
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

position (number) (required)
extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

For more information, see the TypeScript SDK Docs.

GetPosition

Return the current position of the switch.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(int): The current position of the switch within the range of available positions.

Example:

my_switch = Switch.from_robot(robot=machine, name="my_switch")

# Update the switch from its current position to the desired position of 1.
await my_switch.set_position(1)

# Get the current set position of the switch.
pos1 = await my_switch.get_position()

# Update the switch from its current position to the desired position.
await my_switch.set_position(0)

# Get the current set position of the switch.
pos2 = await my_switch.get_position()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(uint32)
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

For more information, see the TypeScript SDK Docs.

GetNumberOfPositions

Return the number of valid positions for this switch.

Parameters:

extra (Mapping[str, Any]) (optional): Extra options to pass to the underlying RPC call.
timeout (float) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

(int): The number of available positions.

Example:

my_switch = Switch.from_robot(robot=machine, name="my_switch")

print(await my_switch.get_number_of_positions())

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

(uint32)
(error): An error, if one occurred.

For more information, see the Go SDK Docs.

Parameters:

extra (None) (optional)
callOptions (CallOptions) (optional)

Returns:

(Promise)

For more information, see the TypeScript SDK Docs.

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. For built-in models, model-specific commands are covered with each model’s documentation. If you are implementing your own switch and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

command (Mapping[str, ValueTypes]) (required): The command to execute.
timeout (float) (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, viam.utils.ValueTypes]): Result of the executed command.

Raises:

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

Example:

my_switch = Switch.from_robot(robot=machine, name="my_switch")
command = {"cmd": "test", "data1": 500}
result = await my_switch.do_command(command)

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
cmd (map[string]interface{}): The command to execute.

Returns:

(map[string]interface{}): The command response.
(error): An error, if one occurred.

Example:

mySwitch, err := switch.FromRobot(machine, "my_switch")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := mySwitch.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

command (Struct) (required): The command to execute.
callOptions (CallOptions) (optional)

Returns:

(Promise<JsonValue>)

Example:

const result = await resource.doCommand({
  name: 'myCommand',
  args: { key: 'value' },
});

For more information, see the TypeScript SDK Docs.

Close

Safely shut down the resource and prevent further use.

Python
Go

Parameters:

None.

Returns:

None.

Example:

my_switch = Switch.from_robot(robot=machine, name="my_switch")
await my_switch.close()

For more information, see the Python SDK Docs.

Parameters:

ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

(error): An error, if one occurred.

Example:

mySwitch, err := switch.FromRobot(machine, "my_switch")

err = mySwitch.Close(context.Background())

For more information, see the Go SDK Docs.

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!