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 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, browse the Viam registry. Each module’s configuration is documented on its registry page.

Steps

1. Add a button component

1. Click the + button.
2. Select Configuration block.
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 Create.

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:

{
  "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 API key and API key ID. Copy the machine address from the Connection details section on the same tab. 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.

pip install viam-sdk

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())

python button_test.py

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

package main

import (
    "context"
    "fmt"

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

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

    robot, err := client.New(ctx, "YOUR-MACHINE-ADDRESS", logger,
        client.WithCredentials(utils.Credentials{
            Type:    utils.CredentialsTypeAPIKey,
            Payload: "YOUR-API-KEY",
        }),
        client.WithAPIKeyID("YOUR-API-KEY-ID"),
    )
    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")
}

go run main.go

Troubleshooting

Related

• Button API reference: full method documentation.
• What is a module?: write a module that responds to button presses.
• Add a component: find the right type for your hardware.