Sensor Component

A sensor is a device that can measure information about the outside world. Add a sensor component to your machine to send the information the sensor measures to the computer controlling the machine.

Most machines with a sensor need at least the following hardware:

  • A board
  • Depending on your sensor’s output type (analog or digital), an analog-to-digital converter (ADC) may be necessary to allow the sensor to communicate with the board

Supported models

To use your sensor with Viam, check whether one of the following built-in models or modular resources supports your sensor.

Built-in models

For configuration information, click on the model name:

ModelDescription
fakeA model used for testing, with no physical hardware.
ultrasonicThe HC-S204 ultrasonic distance sensor
bme280BME280 environmental sensor
ds18b20DallasTemperature DS18B20 digital temperature sensor
sensirion-sht3xdSensirion SHT3x-DIS temperature and humidity sensor

Modular resources

Search for additional sensor models that you can add from the Viam Registry:

For configuration information, click on the model name:

Model
Description

Control your sensor with Viam’s client SDK libraries

To get started using Viam’s SDKs to connect to and control your machine, go to your machine’s page on the Viam app, navigate to the Code sample tab, select your preferred programming language, and copy the sample code generated.

When executed, this sample code will create a connection to your machine as a client. Then control your machine programmatically by adding API method calls as shown in the following examples.

These examples assume you have a sensor called "my_sensor" configured as a component of your machine. If your sensor has a different name, change the name in the code.

Be sure to import the sensor package for the SDK you are using:

from viam.components.sensor import Sensor
import (
  "go.viam.com/rdk/components/sensor"
)

API

The sensor component supports the following methods:

Method NameDescription
GetReadingsGet the measurements or readings that this sensor provides.
GetGeometriesGet all the geometries associated with the sensor in its current configuration, in the frame of the sensor.
DoCommandSend or receive model-specific commands.
CloseSafely shut down the resource and prevent further use.

GetReadings

Get the measurements or readings that this sensor provides.

Parameters:

  • extra (Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.
  • timeout (Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

For more information, see the Python SDK Docs.

my_sensor = Sensor.from_robot(robot=robot, name='my_sensor')

# Get the readings provided by the sensor.
readings = await my_sensor.get_readings()

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

For more information, see the Go SDK Docs.

mySensor, err := sensor.FromRobot(robot, "my_sensor")

// Get the readings provided by the sensor.
readings, err := mySensor.Readings(context.Background(), nil)

GetGeometries

Get all the geometries associated with the sensor in its current configuration, in the frame of the sensor. The motion and navigation services use the relative position of inherent geometries to configured geometries representing obstacles for collision detection and obstacle avoidance while motion planning.

Parameters:

  • extra (Optional[Dict[str, Any]]): Extra options to pass to the underlying RPC call.
  • timeout (Optional[float]): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call.

Returns:

For more information, see the Python SDK Docs.

my_sensor = Sensor.from_robot(robot=robot, name="my_sensor")

geometries = await my_sensor.get_geometries()

if geometries:
    # Get the center of the first geometry
    print(f"Pose of the first geometry's centerpoint: {geometries[0].center}")

DoCommand

Execute model-specific commands that are not otherwise defined by the component API. For built-in models, model-specific commands are covered with each model’s documentation. If you are implementing your own sensor and add features that have no built-in API method, you can access them with DoCommand.

Parameters:

Returns:

my_sensor = Sensor.from_robot(robot=robot, name="my_sensor")

my_calibration_routine = {
  "command": "calibrate",
  "offset": 273
}

await my_sensor.do_command(my_calibration_routine)

For more information, see the Python SDK Docs.

Parameters:

Returns:

mySensor, err := sensor.FromRobot(robot, "my_sensor")

resp, err := mySensor.DoCommand(ctx, map[string]interface{}{"command": "calibrate", "offset": 273})

For more information, see the Go SDK Code.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None

Returns:

  • None
my_sensor = Sensor.from_robot(robot, "my_sensor")

await my_sensor.close()

For more information, see the Python SDK Docs.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Returns:

  • (error) : An error, if one occurred.
mySensor, err := sensor.FromRobot(robot, "my_sensor")

err := mySensor.Close(ctx)

For more information, see the Go SDK Docs.

Troubleshooting

You can find additional assistance in the Troubleshooting section.

You can also ask questions in the Community Discord and we will be happy to help.

Next steps