# 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>`:

```json
{
  "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](https://app.viam.com/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](https://docs.viam.com/build-modules/write-a-driver-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:

```python
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](https://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:

- **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

##### Component not initializing (error in logs)

- Expand the **Error logs** section on the component’s configuration card in the **CONFIGURE** tab. Per-component errors appear there with the module name and error count, isolated from other resources.
- For full `viam-server` logs across every resource, see the **LOGS** tab.
- Verify that the device path or address in your attributes is correct.
- If the component depends on another (for example, a motor that references a board in its attributes), confirm the dependency is configured and working.

##### Model not appearing in search

- The configuration block search covers both built-in models and every module in the Viam registry. Try shorter or broader search terms (for example, “raspberry pi” rather than “rpi5”, or “rtsp” rather than a specific camera brand).
- If the model is from a module, it appears in search results as soon as you start typing. Use the Task type, Framework, or Visibility filters to narrow results instead of relying on exact names.
- For built-in models only: confirm your `viam-server` version is up to date if an expected built-in does not appear.

##### Test panel shows no data or errors

- Confirm the machine is **Live** in the Viam app.
- Check physical connections: cables, power, and wiring.
- Review attributes: wrong pin numbers, incorrect device paths, or typos in attribute names are common causes.
- Check the **LOGS** tab for specific error messages from the component.