Configure hardware components

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

• A type that defines what it can do: camera, motor, sensor, arm, and so on. Every component of the same type exposes the same API, regardless of the underlying hardware.
• A model that implements the component API for your specific hardware. For example, the camera type has models for USB webcams, IP cameras through FFmpeg, and others.
• Attributes that configure how the model talks to your hardware: a device path, a baud rate, a pin mapping, or whatever else the model needs.

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"
      }
    }
  ]
}

For the full JSON structure and dependencies, see Machine configuration.

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.

Browse all available components and services in the Viam registry.

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. For step-by-step guides for specific hardware, see Add a component.

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 Configuration block.
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 Create. 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:

• Device paths (for example, /dev/video0, /dev/ttyUSB0): which physical device to use.
• Pin mappings: which GPIO pins connect to the hardware.
• Communication settings: baud rate, I2C address, SPI bus.
• Operational parameters: resolution, speed limits, update frequency.

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:

• A motor may depend on a board for its GPIO pins.
• An encoder may depend on a board for its interrupt pins.
• A sensor-controlled base depends on a base and a movement sensor.

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

Related

• Add a component: step-by-step guides for each component type.
• Capture and sync data: once your component works, start capturing its data to the cloud.
• What is a module?: write code that reads from sensors and acts on what it finds.