# 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](https://app.viam.com/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](https://app.viam.com/registry). Each module’s configuration is documented on its registry page.

## Steps

### 1. Add a button component

1. Click the **+** button.  
2. Select **Blocks**.  
3. Search for the model that matches your button hardware. Search by  
   manufacturer name, chip, or device type.  
4. 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:

```json
    {}
    ```

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:

```bash
python button_test.py
```

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

Save this as `main.go`:

```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")
}
```

Run it:

```bash
go run main.go
```

## Troubleshooting

##### Button push doesn't trigger anything

- Verify the button component shows as connected in the Viam app.
- If using a GPIO-connected button, check the wiring and pin number.
- Test the button from the Viam app’s test panel first.

##### Button module not found

- Confirm you’ve added the module to your machine’s configuration.
- Check that the module is running. Look for it in the machine’s logs.