Add a button | Add a component

Add a button

Add a button to your machine’s configuration so you can trigger button presses programmatically and represent a physical button in your machine config.

Concepts

A button component represents a momentary push button. The API is intentionally simple: a single Push method that simulates pressing the button. The button API does not listen for or report incoming presses; a module can still react to real presses internally, but from SDK code you only initiate presses.

Physical button hardware typically comes from a module in the Viam registry (search for button) that watches a GPIO pin.

The fake built-in model is useful for testing code without physical hardware.

Built-in models

Registry modules

For hardware the built-in models don’t cover, search for button in the Viam registry. Each module’s configuration is documented on its registry page.

Steps

1. Add a button component

Click the + button.
Select Blocks.
Search for the model that matches your button hardware. Search by
manufacturer name, chip, or device type.
Name your button (for example, my-button) and click Add to machine.

2. Configure button attributes

Attributes vary by module. For the fake model, no attributes are needed:

    {}
    ```

For a GPIO-connected button with a registry module, you’ll typically configure  
the board and pin:

```json
    {
      "board": "my-board",
      "pin": "22"
    }
    ```

Check your module’s documentation in the registry for the full list of  
attributes.

### 3. Save and test

Click **Save**, then expand the **Test** section.

- Click **Push** to simulate pressing the button.

## Try it

Push the button programmatically.

To get the credentials for the code below, go to your machine’s page in the Viam app, click the **CONNECT** tab, and select **API keys**.  
Copy the **Key** and **ID**.  
Then click the **CONFIGURE** tab, and click **Details**, and copy the **Remote address**.  
When you run the code below, the button’s Push method fires. With a physical button connected with a module, this triggers whatever action the module defines.

- [Python](https://docs.viam.com/hardware/common-components/add-a-button/#tabset-hardwarecommon-componentsadd-a-button-1-0)
- [Go](https://docs.viam.com/hardware/common-components/add-a-button/#tabset-hardwarecommon-componentsadd-a-button-1-1)

Install the Viam Python SDK in a virtual environment by following [Install the Python SDK](https://docs.viam.com/reference/sdks/python/python-venv/).

Save this as `button_test.py`:

```python
import asyncio
from viam.robot.client import RobotClient
from viam.components.button import Button

async def main():
    opts = RobotClient.Options.with_api_key(
        api_key="YOUR-API-KEY",
        api_key_id="YOUR-API-KEY-ID"
    )
    robot = await RobotClient.at_address("YOUR-MACHINE-ADDRESS", opts)

button = Button.from_robot(robot, "my-button")

# Push the button
    print("Pushing button...")
    await button.push()
    print("Button pushed")

await robot.close()

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python button_test.py

mkdir button-test && cd button-test
go mod init button-test
go get go.viam.com/rdk

Save this as main.go:

package main

import (
    "context"
    "fmt"

"go.viam.com/rdk/components/button"
    "go.viam.com/rdk/logging"
    "go.viam.com/rdk/robot/client"
)

func main() {
    ctx := context.Background()
    logger := logging.NewLogger("button-test")

robot, err := client.New(ctx, "YOUR-MACHINE-ADDRESS", logger,
        client.WithDialOptions(client.WithEntityCredentials(
            "YOUR-API-KEY-ID",
            client.Credentials{
                Type:    client.CredentialsTypeAPIKey,
                Payload: "YOUR-API-KEY",
            })),
    )
    if err != nil {
        logger.Fatal(err)
    }
    defer robot.Close(ctx)

b, err := button.FromProvider(robot, "my-button")
    if err != nil {
        logger.Fatal(err)
    }

// Push the button
    fmt.Println("Pushing button...")
    if err := b.Push(ctx, nil); err != nil {
        logger.Fatal(err)
    }
    fmt.Println("Button pushed")
}