Add a board

Add a board to your machine’s configuration so other components can use your single-board computer’s GPIO pins, analog readers, and digital interrupts.

Concepts

A board component exposes the low-level I/O on your single-board computer:

• GPIO pins: digital output (high/low) and PWM.
• Analog readers: read analog voltage values from ADC-capable pins.
• Digital interrupts: react to signal changes on a pin.

The board doesn’t represent external hardware. It represents the I/O capabilities of the computer itself. Motors, encoders, and servos reference the board by name to access the pins they’re wired to. Browse all available board models in the Viam registry.

Steps

1. Open your machine in the Viam app

Go to app.viam.com and navigate to your machine. Confirm it shows as Live in the upper left.

2. Add a board component

1. Click the + button.
2. Select Configuration block.
3. Search for the model that matches your single-board computer:
   • For a Raspberry Pi (any model), search for pi.
   • For an NVIDIA Jetson, search for jetson.
   • For an Orange Pi, search for orangepi.
4. Name your board (for example, my-board) and click Create.

3. Configure board attributes

For most single-board computers, the board works with no additional configuration. The model auto-detects available pins.

If you need analog readers or digital interrupts, add them in the attributes:

Analog readers:

{
  "analogs": [
    {
      "name": "my-analog",
      "pin": "32",
      "spi_bus": "main",
      "chip_select": "0",
      "channel": 0
    }
  ]
}

Digital interrupts:

{
  "digital_interrupts": [
    {
      "name": "my-interrupt",
      "pin": "37"
    }
  ]
}

4. Save the configuration

Click Save in the upper right. viam-server initializes the board immediately. No restart needed.

5. Test the board

1. Find your board in the configuration view.
2. Expand the Test section.
3. Try setting a GPIO pin high or low, or read an analog value.

If you have an LED wired to a GPIO pin, setting the pin high should light it up.

Try it

Toggle a GPIO pin and read its state 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 SDK code sample. Toggle Include API key on. Copy the machine address, API key, and API key ID from the code sample. If you have an LED wired to pin 11, you’ll see it turn on and off when you run the code below.

pip install viam-sdk

import asyncio
from viam.robot.client import RobotClient
from viam.components.board import Board


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)

    board = Board.from_robot(robot, "my-board")
    pin = await board.gpio_pin_by_name("11")

    await pin.set(True)
    state = await pin.get()
    print(f"Pin 11 is {'high' if state else 'low'}")

    await pin.set(False)
    state = await pin.get()
    print(f"Pin 11 is {'high' if state else 'low'}")

    await robot.close()

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

python board_test.py

Pin 11 is high
Pin 11 is low

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

package main

import (
    "context"
    "fmt"

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

func main() {
    ctx := context.Background()
    logger := logging.NewLogger("board-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)

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

    pin, err := myBoard.GPIOPinByName("11")
    if err != nil {
        logger.Fatal(err)
    }

    if err := pin.Set(ctx, true, nil); err != nil {
        logger.Fatal(err)
    }
    state, err := pin.Get(ctx, nil)
    if err != nil {
        logger.Fatal(err)
    }
    fmt.Printf("Pin 11 is high: %v\n", state)

    if err := pin.Set(ctx, false, nil); err != nil {
        logger.Fatal(err)
    }
    state, err = pin.Get(ctx, nil)
    if err != nil {
        logger.Fatal(err)
    }
    fmt.Printf("Pin 11 is high: %v\n", state)
}

go run main.go

Troubleshooting

What’s next

• Board API reference: full method documentation.
• Add a Motor: wire a motor to your board’s GPIO pins.
• Add an Encoder: wire an encoder to your board’s interrupt pins.
• Add a Servo: control a servo from a PWM-capable pin.