Button API

The button API allows you to get button presses from your button components.

The button component supports the following methods:

Method NameDescriptionviam-micro-server Support
PushPush the button.

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

GetStatusGet the current status of the button as a map of key-value pairs describing its state.
GetResourceNameGet the ResourceName for this button.
CloseSafely shut down the resource and prevent further use.

API

Push

Push the button. 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:

  • None.

Example:

my_button = Button.from_robot(robot=machine, name="my_button")

# Push the button
await my_button.push()

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:

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

Example:

myButton, err := switch.FromProvider(machine, "my_button")

err := myButton.Push(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

  • (Promise)

Example:

const button = new VIAM.ButtonClient(machine, 'my_button');

// Push the button
await button.push();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

await myButton.push();

For more information, see the Flutter SDK Docs.

Reconfigure

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

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • deps (Dependencies): The resource dependencies.
  • conf (Config): The resource configuration.

Returns:

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

For more information, see the Go 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 button 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_button = Button.from_robot(robot=machine, name="my_button")
command = {"cmd": "test", "data1": 500}
result = await my_button.do_command(command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myButton, err := button.FromProvider(machine, "my_button")

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

For more information, see the Go SDK Docs.

Parameters:

  • command (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
  • callOptions (CallOptions) (optional)

Returns:

Example:

// Plain object (recommended)
const result = await resource.doCommand({
  myCommand: { key: 'value' },
});

// Struct (still supported)
import { Struct } from '@viamrobotics/sdk';

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

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

// Example using doCommand with an arm component
const command = {'cmd': 'test', 'data1': 500};
var result = myArm.doCommand(command);

For more information, see the Flutter SDK Docs.

GetStatus

Get the current status of the button as a map of key-value pairs describing its state.

Parameters:

  • 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]): : The status of the component.

Example:

status = await component.get_status()

For more information, see the Python SDK Docs.

Parameters:

  • callOptions (CallOptions) (optional)

Returns:

For more information, see the TypeScript SDK Docs.

Parameters:

  • None.

Returns:

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this button.

Parameters:

  • name (str) (required): The name of the Resource.

Returns:

Example:

my_button_name = Button.get_resource_name("my_button")

For more information, see the Python SDK Docs.

Parameters:

  • None.

Returns:

Example:

myButton, err := button.FromProvider(machine, "my_button")

err = myButton.Name()

For more information, see the Go SDK Docs.

Parameters:

  • None.

Returns:

  • (string): The name of the resource.

Example:

button.name

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

// Example:
var name = Button.getResourceName('my_button');

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

my_button = Button.from_robot(robot=machine, name="my_button")
await my_button.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:

myButton, err := button.FromProvider(machine, "my_button")

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

For more information, see the Go SDK Docs.