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.

GetGeometriesGet all the geometries associated with the sensor in its current configuration, in the frame of the sensor.
ReconfigureReconfigure this resource.
DoCommandExecute model-specific commands that are not otherwise defined by the component API.
GetResourceNameGet the ResourceName for this sensor.
CloseSafely shut down the resource and prevent further use.

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:

  • extra (None) (optional)
  • callOptions (CallOptions) (optional)

Returns:

Example:

const sensor = new VIAM.SensorClient(machine, 'my_sensor');

// Get the readings of a sensor.
const readings = await sensor.getReadings();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var readings = await mySensor.readings();

For more information, see the Flutter SDK Docs.

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 (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:

Example:

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

For more information, see the Python 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. Most models do not implement DoCommand. Any available model-specific commands should be covered in the model’s documentation. If you are implementing your own sensor and want to add features that have no corresponding built-in API method, you can implement them with DoCommand.

Parameters:

  • command (Mapping[str, ValueTypes]) (required): The command to execute.
  • 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.ValueTypes]): : Result of the executed command.

Raises:

  • (NotImplementedError): Raised if the Resource does not support arbitrary commands.

Example:

my_sensor = Sensor.from_robot(robot=machine, name="my_sensor")
command = {"cmd": "test", "data1": 500}
result = await my_sensor.do_command(command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

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

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := mySensor.DoCommand(context.Background(), command)

For more information, see the Go SDK Docs.

Parameters:

  • command (Struct) (required): The command to execute. Accepts either a Struct or a plain object, which will be converted automatically.
  • callOptions (CallOptions) (optional)

Returns:

Example:

// Plain object (recommended)
const result = await resource.doCommand({
  myCommand: { key: 'value' },
});

// Struct (still supported)
import { Struct } from '@viamrobotics/sdk';

const result = await resource.doCommand(
  Struct.fromJson({ myCommand: { key: 'value' } })
);

For more information, see the TypeScript SDK Docs.

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.

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:

  • None.

Returns:

Example:

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

err = mySensor.Name()

For more information, see the Go SDK Docs.

Parameters:

  • None.

Returns:

  • (string): The name of the resource.

Example:

sensor.name

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

final mySensorResourceName = mySensor.getResourceName("my_sensor");

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.FromProvider(machine, "my_sensor")

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

For more information, see the Go SDK Docs.