Edit

Component types

Every component on your machine has a type that determines its API, which defines what methods your code can call on it. Choosing the right type means platform features like data capture, test panels, and the SDKs work with your hardware automatically.

Sensing

These components read information from the physical world.

Type	What it does	Examples
Camera	Captures 2D images or 3D point clouds	USB webcams, IP cameras, depth cameras, lidar
Encoder	Tracks rotational or linear position	Incremental encoders, absolute encoders
Movement sensor	Reports position, orientation, velocity, or angular velocity	GPS, IMU, accelerometer, gyroscope, odometry
Power sensor	Reports voltage, current, and power consumption	INA219, INA226, current clamps
Sensor	Returns key-value readings	Temperature, humidity, air quality, distance sensors

Actuation

These components make things move.

Type	What it does	Examples
Arm	Controls a multi-jointed robotic arm	xArm, UR5, custom serial arms
Base	Moves a mobile robot as a unit (no need to command individual motors)	Wheeled rovers, tracked vehicles, holonomic platforms
Gantry	Moves along linear rails with precise positioning	Single-axis stages, multi-axis CNC gantries
Gripper	Opens and closes a grasping device	Parallel-jaw grippers, vacuum grippers
Motor	Drives rotational or linear motion with speed and position control	DC motors, stepper motors, brushless motors
Servo	Moves to precise angular positions	Hobby servos, PWM-controlled actuators

Interface

These components provide low-level hardware access or human input.

Type	What it does	Examples
Board	Exposes GPIO pins, analog readers, and digital interrupts	Raspberry Pi GPIO, Arduino, custom I/O boards
Button	Reads presses from a physical button	Momentary switches, push buttons
Generic	Catch-all for hardware that doesn’t fit another type	Custom devices with non-standard interfaces
Input controller	Reads human input from control devices	Gamepads, joysticks, custom button panels
Switch	Reads position from a multi-position switch	Toggle switches, selector switches

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 DoCommand for 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.

Models

Each component type has one or more models: drivers that know how to communicate with specific hardware. Some models ship with viam-server (like webcam for USB cameras or gpio for motors). Most hardware-specific models come from the Viam registry. All models work the same way regardless of where they come from.

If no model exists for your hardware, you can write a driver module that implements the standard API for your device.

Switching hardware without changing code

Because every model of a given type exposes the same API, your application code doesn’t 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.

What’s next

How components work: understand components and walk through adding any component to your machine.
Add a component: step-by-step guides for each component type.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!