Add a board | Add a component

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:

Most of the time a board represents the single-board computer itself (Raspberry Pi, Jetson, Orange Pi). A board can also represent an IO expander such as the PCA9685 or a microcontroller connected over serial that exposes GPIO-like interfaces. In both cases, motors, encoders, and servos reference the board by name to access the pins they’re wired to.

Search for board in the Viam registry to see available models.

Pin numbering

Viam uses the board pin number (the physical pin number printed on the header) in GPIO configuration, not the GPIO/BCM number or alternate schemes. When a model’s docs show a pinout, confirm which numbering scheme matches the number you configure.

Built-in models

Micro-RDK:

Registry modules

Viam-maintained board modules:

Module Boards supported
viam:raspberry-pi Raspberry Pi variants: rpi5, rpi4, rpi3, rpi2, rpi1, rpi0, rpi0_2
viam:nvidia NVIDIA Jetson Orin, AGX, and Nano
viam:texas-instruments Texas Instruments TDA4VM board
viam:pca PCA9685 16-channel PWM IO expander

For boards not covered above, search for board 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 Blocks.
  3. Search for the model that matches your hardware:
    • For a Raspberry Pi, search for raspberry pi and pick the model that matches your Pi version (for example, viam:raspberry-pi:rpi5).
    • For an NVIDIA Jetson, search for jetson.
    • For an Orange Pi, search for orangepi.
    • For an IO expander, search for it by chip name (for example, pca9685).
  4. Name your board (for example, my-board) and click Add to machine.

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 API keys. Copy the Key and ID. Then click the CONFIGURE tab, and click Details, and copy the Remote address. If you have an LED wired to pin 11, you’ll see it turn on and off when you run the code below.

Install the Viam Python SDK in a virtual environment by following Install the Python SDK.

Save this as board_test.py:

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

Run it:

python board_test.py

You should see:

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

Save this as main.go:

package main

import (
    "context"
    "fmt"

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

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

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

Run it:

go run main.go

Troubleshooting

Board model not available
GPIO pin doesn't respond
Analog reader returns unexpected values

If your board is not working as expected, follow these steps:

  1. Check your machine logs on the LOGS tab to check for errors.
  2. Review this board model’s documentation to ensure you have configured all required attributes.
  3. Check that all wires are securely connected.
  4. Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the board there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.