Configure hardware components | Viam Documentation

Configure hardware components

Viam represents every piece of physical hardware on your machine as a component. Each component has three things:

In your machine’s configuration, each component is a JSON block. The type appears in the api field as rdk:component:<type>:

{
  "components": [
    {
      "name": "my-camera",
      "api": "rdk:component:camera",
      "model": "webcam",
      "attributes": {
        "video_path": "/dev/video0"
      }
    }
  ]
}

Models

When you add a component, you search for a model that matches your hardware. A model is an implementation of a component API for one piece of hardware (or class of hardware). Some models ship with viam-server (like webcam for USB cameras or gpio for motors wired to GPIO pins). Most hardware-specific models (arms, grippers, specialized sensors, motor controllers) come from modules in the Viam registry; a module is a code package that provides one or more models.

You don’t need to think about where a model comes from. The Viam app shows all available models in one search, and they all work the same way: same API, same data capture, same test sections, same SDKs.

If no model exists for your hardware, you can write your own module that provides a model implementing the component API.

Switching hardware without changing code

Because every model of a given type exposes the same API, your application code does not change when you swap hardware. For example, this Python code reads a motor’s position:

motor = Motor.from_robot(robot, "drive-motor")
position = await motor.get_position()

This works whether drive-motor is configured as a gpio motor on a Raspberry Pi, a Trinamic stepper over CAN bus, or an ODrive brushless controller. To switch hardware, you change the model and attributes in your machine’s configuration. Your code stays the same.

Add a component

The process for adding any component is the same whether you’re adding a motor, a sensor, a board, or anything else.

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. If it shows as offline, verify that viam-server is running on your machine.

2. Add the component

  1. Click the + button.
  2. Select Blocks.
  3. Search for the model that matches your hardware (for example, “webcam”, “gpio motor”, “xArm6”). The search covers all available models and fragments.
  4. Give your component a name and click Add to machine. The name is how you reference it in code and configuration, so keep it short, descriptive, and unique on this machine.

3. Configure attributes

After creating the component, you’ll see its configuration panel. Every model has its own set of attributes. These settings tell the model how to communicate with your specific hardware.

Common attributes include:

Check the model’s reference page for the full list of attributes and their defaults. You can configure attributes using the form fields in the UI, or switch to JSON mode to edit the configuration directly.

4. Set up dependencies (if needed)

Some components depend on other components. For example:

If your component depends on another, that other component must already exist in your configuration. The model’s reference page documents required dependencies.

5. Save the configuration

Click Save in the upper right of the configuration panel.

When you save, viam-server automatically reloads the configuration and initializes the new component. You do not need to restart anything.

6. Test the component

Every component in Viam has a test section on its component card in the CONFIGURE tab. The test section uses the same API your code will use, so if the component works here, it will work in your programs.

  1. Find your component in the configuration view.
  2. Expand the test section at the bottom of the component card.
  3. Interact with the component:
    • Camera: toggle the stream or capture an image.
    • Motor: set power or move to a position.
    • Sensor: view live readings.
    • Servo: move to an angle.
    • Board: read or set GPIO pin states.

If the test section shows expected results, your component is configured correctly.

Troubleshooting

Component not initializing (error in logs)
Model not appearing in search
Test panel shows no data or errors