Sensor API

The sensor API allows you to get measurements from your sensor components.

The sensor component supports the following methods:

Method NameDescriptionviam-micro-server Support
GetReadingsGet the measurements or readings that this sensor provides.

ReconfigureReconfigure this resource.

DoCommandExecute model-specific commands that are not otherwise defined by the component API.
GetResourceNameGet the ResourceName for this sensor with the given name.

CloseSafely shut down the resource and prevent further use.

Establish a connection

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

To show your machine’s API key in the sample code, toggle Include API key.

When executed, this sample code creates a connection to your machine as a client.

The following 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.

Import the sensor package for the SDK you are using:

from viam.components.sensor import Sensor

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

API

GetReadings

Get the measurements or readings that this sensor provides. Supported by viam-micro-server.

Parameters:

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

Returns:

  • (Mapping[str, viam.utils.SensorReading]): The measurements. Can be of any type.

Example:

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

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

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.
  • extra (map[string]interface{}): Extra options to pass to the underlying RPC call.

Returns:

  • (map[string]interface{}): A map containing the measurements from the sensor. Contents depend on sensor model and can be of any type.
  • (error): An error, if one occurred.

Example:

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

For more information, see the Go SDK Docs.

Parameters:

Returns:

Example:

var readings = await mySensor.readings();

For more information, see the Flutter SDK Docs.

Reconfigure

Reconfigure this resource. Reconfigure must reconfigure the resource atomically and in place.

Parameters:

  • ctx (Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.
  • deps (Dependencies): The resource dependencies.
  • conf (Config): The resource configuration.

Returns:

  • (error): An error, if one occurred.

For more information, see the Go SDK Docs.

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:

Example:

// Example using doCommand with an arm component
const command = {'cmd': 'test', 'data1': 500};
var result = myArm.doCommand(command);

For more information, see the Flutter SDK Docs.

GetResourceName

Get the ResourceName for this sensor with the given name.

Parameters:

  • name (str) (required): The name of the Resource.

Returns:

Example:

my_sensor_name = Sensor.get_resource_name("my_sensor")

For more information, see the Python SDK Docs.

Parameters:

Returns:

For more information, see the Flutter SDK Docs.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None.

Returns:

  • None.

Example:

my_sensor = Sensor.from_robot(robot=machine, name="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.

Example:

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

err = mySensor.Close(context.Background())

For more information, see the Go SDK Docs.

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.