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 NameDescriptionviam-micro-server Support
SetPositionSet the position of the switch.

GetPositionReturn the current position of the switch.

GetNumberOfPositionsReturn the number of valid positions for this switch.

DoCommandExecute model-specific commands that are not otherwise defined by the component API.

CloseSafely 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.

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)

Example:

const mySwitch = new VIAM.SwitchClient(machine, 'my_switch');

// Update the switch from its current position to position 1
await mySwitch.setPosition(1);

// Update the switch from its current position to position 0
await mySwitch.setPosition(0);

For more information, see the TypeScript SDK Docs.

GetPosition

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

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:

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

  • (Promise)

Example:

const mySwitch = new VIAM.SwitchClient(machine, 'my_switch');

// Update the switch to position 1
await mySwitch.setPosition(1);

// Get the current set position
const pos1 = await mySwitch.getPosition();

// Update the switch to position 0
await mySwitch.setPosition(0);

// Get the current set position
const pos2 = await mySwitch.getPosition();

For more information, see the TypeScript SDK Docs.

GetNumberOfPositions

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

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:

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

  • (Promise)

Example:

const mySwitch = new VIAM.SwitchClient(machine, 'my_switch');

// Get the number of available positions
const numPositions = await mySwitch.getNumberOfPositions();
console.log('Number of positions:', numPositions);

For more information, see the TypeScript SDK Docs.

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. Supported by viam-micro-server.

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:

Returns:

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:

Example:

import { Struct } from '@viamrobotics/sdk';

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

For more information, see the TypeScript SDK Docs.

Close

Safely shut down the resource and prevent further use.

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.

Previous

Servo