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.

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.

Browse all available board models in the Viam registry.

Built-in models

• fake — A model used for testing, with no physical hardware.

Micro-RDK:

• esp32 — (no description).

Registry modules

Viam-maintained board modules:

For boards not covered above, browse all board modules 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 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 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 API keys. Copy the API key and API key ID. Copy the machine address from the Connection details section on the same tab. 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

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.

Related

• 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.