Movement sensor API

The movement sensor API allows you to give commands to your movement sensor components for getting a GPS location, linear velocity and acceleration, angular velocity and acceleration and heading.

Different movement sensors provide different data, so be aware that not all of the methods below are supported by all movement sensors.

Method NameDescriptionModels That Support This Methodviam-micro-server Support
GetPositionGet the current latitude, longitude and altitude.GPS models, wheeled-odometry

GetLinearVelocityGet the current linear velocity as a 3D vector.GPS models, wheeled-odometry

GetAngularVelocityGet the current angular velocity as a 3D vector.IMU models, gyro-mpu6050, and wheeled-odometry

GetLinearAccelerationGet the current linear acceleration as a 3D vector.IMU models, accel-adxl345, and gyro-mpu6050

GetCompassHeadingGet the current compass heading in degrees.GPS models

GetOrientationGet the current orientation.IMU models, wheeled-odometry
GetPropertiesGet the supported properties of this sensor.all models

GetAccuracyGet the accuracy of the various sensors.GPS models
GetReadingsObtain the measurements/data specific to this sensor.all models

DoCommandSend or receive model-specific commands.all models

CloseSafely shut down the resource and prevent further use.all models

API

GetLinearVelocity

Report the current linear velocity in the x, y and z directions (as a 3D vector) in meters per second.

Supported by GPS models. 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:

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the current linear velocity of the movement sensor.
lin_vel = await my_movement_sensor.get_linear_velocity()

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:

  • (r3.Vector): A 3D vector containing three floats representing the linear velocity in the x, y and z directions in meters per second.
  • (error): An error, if one occurred.

Example:

// Get the current linear velocity of the movement sensor.
linVel, err := myMovementSensor.LinearVelocity(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const linearVelocity = await movementSensor.getLinearVelocity();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var linVel = await myMovementSensor.linearVelocity();

For more information, see the Flutter SDK Docs.

GetAngularVelocity

Report the current angular velocity about the x, y and z axes (as a 3D vector) in degrees per second.

Supported by IMU models and by gyro-mpu6050. 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:

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the current angular velocity of the movement sensor.
ang_vel = await my_movement_sensor.get_angular_velocity()

# Get the y component of angular velocity.
y_ang_vel = ang_vel.y

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:

  • (spatialmath.AngularVelocity): A 3D vector containing three floats representing the angular velocity about the x, y and z axes in degrees per second.
  • (error): An error, if one occurred.

Example:

// Get the current angular velocity of the movement sensor.
angVel, err := myMovementSensor.AngularVelocity(context.Background(), nil)

// Get the y component of angular velocity.
yAngVel := angVel.Y

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const angularVelocity = await movementSensor.getAngularVelocity();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var angVel = await myMovementSensor.angularVelocity();

For more information, see the Flutter SDK Docs.

GetCompassHeading

Report the current compass heading in degrees.

Supported by GPS models. 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:

  • (float): : The compass heading in degrees.

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the current compass heading of the movement sensor.
heading = await my_movement_sensor.get_compass_heading()

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:

  • (float64): The compass heading in degrees (between 0 and 360).
  • (error): An error, if one occurred.

Example:

// Get the current compass heading of the movement sensor.
heading, err := myMovementSensor.CompassHeading(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

  • (Promise)

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const compassHeading = await movementSensor.getCompassHeading();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var compassHeading = await myMovementSensor.compassHeading();

For more information, see the Flutter SDK Docs.

GetOrientation

Report the current orientation of the sensor.

Supported by IMU models.

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_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the current orientation vector of the movement sensor.
orientation = await my_movement_sensor.get_orientation()

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:

  • (spatialmath.Orientation): Abstract base class for protocol messages, containing o_x, o_y, o_z, and theta, which together represent a vector pointing in the direction that the sensor is pointing, and the angle (theta) in degrees of the sensor’s rotation about that axis.
  • (error): An error, if one occurred.

Example:

// Get the current orientation of the movement sensor.
sensorOrientation, err := myMovementSensor.Orientation(context.Background(), nil)

// Get the orientation vector.
orientation := sensorOrientation.OrientationVectorDegrees()

// Print out the orientation vector.
logger.Info("The x component of the orientation vector: ", orientation.OX)
logger.Info("The y component of the orientation vector: ", orientation.OY)
logger.Info("The z component of the orientation vector: ", orientation.OZ)
logger.Info("The number of degrees that the movement sensor is rotated about the vector: ", orientation.Theta)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const orientation = await movementSensor.getOrientation();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var orientation = await myMovementSensor.orientation();

For more information, see the Flutter SDK Docs.

GetPosition

Report the current GeoPoint (latitude, longitude) and altitude (in meters).

Supported by GPS models. 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:

  • (Tuple[viam.components.movement_sensor.GeoPoint, float]): : The current lat/long, along with the altitude in m.

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot,
    name="my_movement_sensor")

# Get the current position of the movement sensor.
position = await my_movement_sensor.get_position()

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:

Example:

// Get the current position of the movement sensor above sea level in meters.
position, altitude, err := myMovementSensor.Position(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const position = await movementSensor.getPosition();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var position = await myMovementSensor.position();
var altitude = position.altitude;
var coordinates = position.coordinates;

For more information, see the Flutter SDK Docs.

GetProperties

Get the supported properties of this sensor. 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:

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the supported properties of the movement sensor.
properties = await my_movement_sensor.get_properties()

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:

Example:

// Get the supported properties of the movement sensor.
properties, err := myMovementSensor.Properties(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const properties = await movementSensor.getProperties();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var props = await myMovementSensor.properties();

For more information, see the Flutter SDK Docs.

GetAccuracy

Get the reliability metrics of the movement sensor, including various parameters to assess the sensor’s accuracy and precision in different dimensions.

Supported by GPS models and imu-wit.

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_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the accuracy of the movement sensor.
accuracy = await my_movement_sensor.get_accuracy()

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:

  • (*Accuracy): The precision and reliability metrics of the movement sensor, which vary depending on model. This type contains the following fields:

    • AccuracyMap (map[string]float32): A mapping of specific measurement parameters to their accuracy values. The keys are string identifiers for each measurement (for example, “Hdop”, “Vdop”), and the values are their corresponding accuracy levels as float32.
    • Hdop (float32): Horizontal Dilution of Precision (HDOP) value. It indicates the level of accuracy of horizontal measurements. Lower values indicate improved reliability of positional measurements.
    • Vdop (float32): Vertical Dilution of Precision (VDOP) value. Similar to HDOP, it denotes the accuracy level of vertical measurements. Lower values indicate improved reliability of positional measurements.
    • NmeaFix (int32): An integer value representing the quality of the NMEA fix. See Novatel documentation for the meaning of each fix value.
    • CompassDegreeError (float32): The estimated error in compass readings, measured in degrees. This signifies the deviation or uncertainty in the sensor’s compass measurements. A lower value implies a more accurate compass direction.

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

Example:

// Get the accuracy of the movement sensor.
accuracy, err := myMovementSensor.Accuracy(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const accuracy = await movementSensor.getAccuracy();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var accuracy = await myMovementSensor.accuracy();

For more information, see the Flutter SDK Docs.

GetLinearAcceleration

Report the current linear acceleration in the x, y and z directions (as a 3D vector) in meters per second per second.

Supported by IMU models, accel-adxl345, and gyro-mpu6050. 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:

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the current linear acceleration of the movement sensor.
lin_accel = await my_movement_sensor.get_linear_acceleration()

# Get the x component of linear acceleration.
x_lin_accel = lin_accel.x

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:

  • (r3.Vector): A 3D vector containing three floats representing the linear acceleration in the x, y and z directions in meters per second per second (m/s2).
  • (error): An error, if one occurred.

Example:

// Get the current linear acceleration of the movement sensor.
linAcc, err := myMovementSensor.LinearAcceleration(context.Background(), nil)

For more information, see the Go SDK Docs.

Parameters:

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

Returns:

Example:

const movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const linearAcceleration =
  await movementSensor.getLinearAcceleration();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var linAccel = await myMovementSensor.linearAcceleration();

For more information, see the Flutter SDK Docs.

GetGeometries

Get all the geometries associated with the movement sensor in its current configuration, in the frame of the movement 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_movement_sensor = MovementSensor.from_robot(robot=machine, name="my_movement_sensor")
geometries = await my_movement_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.

GetReadings

Get all the measurements/data from the sensor. Results depend on the sensor model and can be of any type. If a sensor is not configured to take a certain measurement or fails to read a piece of data, that data will not appear in the readings dictionary. 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 readings for the MovementSensor. Can be of any type.

Example:

my_movement_sensor = MovementSensor.from_robot(
    robot=robot, name="my_movement_sensor")

# Get the latest readings from the movement sensor.
readings = await my_movement_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 movementSensor = new VIAM.MovementSensorClient(
  machine,
  'my_movement_sensor'
);
const readings = await movementSensor.getReadings();

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

var readings = await myMovementSensor.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. 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 movement sensor and want to add features that have no corresponding built-in API method, you can implement them with DoCommand. Supported by viam-micro-server.

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_movement_sensor = MovementSensor.from_robot(robot=machine, name="my_movement_sensor")
command = {"cmd": "test", "data1": 500}
result = await my_movement_sensor.do_command(command)

For more information, see the Python SDK Docs.

Parameters:

Returns:

Example:

myMovementSensor, err := movement_sensor.FromProvider(machine, "my_movement_sensor")

command := map[string]interface{}{"cmd": "test", "data1": 500}
result, err := myMovementSensor.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 movement sensor.

Parameters:

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

Returns:

Example:

my_movement_sensor_name = MovementSensor.get_resource_name("my_movement_sensor")

For more information, see the Python SDK Docs.

Parameters:

  • None.

Returns:

Example:

myMovementSensor, err := movementsensor.FromProvider(machine, "my_movement_sensor")

err = myMovementSensor.Name()

For more information, see the Go SDK Docs.

Parameters:

  • None.

Returns:

  • (string): The name of the resource.

Example:

movement_sensor.name

For more information, see the TypeScript SDK Docs.

Parameters:

Returns:

Example:

final myMovementSensorResourceName = myMovementSensor.getResourceName("my_movement_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_movement_sensor = MovementSensor.from_robot(robot=machine, name="my_movement_sensor")
await my_movement_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:

myMovementSensor, err := movementsensor.FromProvider(machine, "my_movement_sensor")

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

For more information, see the Go SDK Docs.