Add a component | Viam Documentation
Add a component
Every component on your machine has a type that determines its API, which defines what methods your code can call on it. Pick the type whose API best describes what your hardware does, then use the per-type guide to add a model and configure it. The general add-a-component process is the same for every type. For the universal steps, see Configure hardware components.
The Features column lists platform integrations the type is part of. Every type supports DoCommand and shows a test panel on its configuration card, so those aren’t repeated in the column; exceptions are called out where they apply. Data capture means the built-in data manager can capture this type’s output to the Viam cloud. Readings means the type returns a flat key-value snapshot through the GetReadings method, on top of its type-specific API.
Control an arm, gripper, or gantry
| Component | What it does | Examples | Features |
|---|---|---|---|
| Arm | Control a multi-joint robotic arm: move joints, position the end effector, integrate with motion planning. | xArm, UR5, custom serial arms | — |
| Gripper | Open, close, and grasp objects with a gripper mounted on an arm or gantry. | Parallel-jaw grippers, vacuum grippers | — |
| Gantry | Move a tool head, camera, or sensor to precise coordinates along one or more linear axes. | Single-axis stages, multi-axis CNC gantries | — |
Sensing
Components that read data from the physical world.
| Component | What it does | Examples | Features |
|---|---|---|---|
| Camera | Capture images or video from a USB webcam, IP camera, or depth sensor. | USB webcams, IP cameras, depth cameras, lidar | Data capture |
| Sensor | Read environmental data: temperature, humidity, distance, air quality, and more. | Temperature, humidity, air quality, distance sensors | Data capture · Readings |
| Movement sensor | Get position, velocity, orientation, or compass heading from a GPS, IMU, or odometry source. | GPS, IMU, accelerometer, gyroscope, odometry | Data capture · Readings |
| Power sensor | Monitor voltage, current, and power consumption. | INA219, INA226, current clamps | Data capture · Readings |
| Encoder | Track how far a motor has turned and how fast it’s spinning. | Incremental encoders, absolute encoders | Data capture |
| Audio input | Stream audio from a microphone or audio-in device. | USB microphones, Pi audio-in HATs | Data capture · No test panel |
Drive a mobile robot
| Component | What it does | Examples | Features |
|---|---|---|---|
| Base | Drive a mobile robot with movement commands like “move forward 300mm” or “spin 90 degrees.” A base wraps your drive system into a single interface. | Wheeled rovers, tracked vehicles, holonomic platforms | — |
Control motors and servos
| Component | What it does | Examples | Features |
|---|---|---|---|
| Motor | Control a DC or stepper motor through a motor driver and GPIO pins. | DC motors, stepper motors, brushless motors | Data capture |
| Servo | Set the angular position of a hobby servo with a PWM pin. | Hobby servos, PWM-controlled actuators | — |
Inputs and GPIO
Components for physical I/O and user input.
| Component | What it does | Examples | Features |
|---|---|---|---|
| Board | Expose GPIO pins, analog readers, and digital interrupts from a single-board computer. Many other components depend on a board. | Raspberry Pi GPIO, ESP32, PCA9685 IO expander | — |
| Button | Detect presses from a physical button to trigger actions. | Momentary switches, push buttons | — |
| Switch | Read or set the position of a toggle or selector switch. | Toggle switches, selector switches | — |
| Input controller | Use a gamepad, joystick, or other input device for manual machine control. | Gamepads, joysticks, custom button panels | — |
Other
| Component | What it does | Examples | Features |
|---|---|---|---|
| Generic | Interface with hardware that doesn’t fit any standard component type. | Custom devices with non-standard interfaces | — |
| Audio output | Play audio on a speaker or audio-out device. | USB speakers, audio-out HATs | No test panel |
Choosing a type
Match your hardware to the type whose API best describes what it does:
- If it produces images, use camera.
- If it produces readings (temperature, distance, pressure), use sensor.
- If it reports position or motion (GPS, IMU), use movement sensor.
- If it spins or drives linear motion, use motor.
- If it moves to an angle, use servo.
- If you need direct GPIO access, use board.
- If nothing fits, use generic. It provides
DoCommandfor arbitrary interactions.
Every type also has a DoCommand method for functionality beyond the standard API. For example, a sensor that also has a calibration routine can expose calibration through DoCommand while still using GetReadings for its primary data.