Movement Sensor Component

A movement sensor component is a sensor that gives data on where a machine is and how fast it is moving. Examples of movement sensors include global positioning systems (GPS), inertial measurement units (IMUs), accelerometers and gyroscopes.

Supported models

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

Built-in models

Viam supports several different models of movement sensor. For configuration information, click on the model name:

ModelDescription
gps-nmeaNMEA-based GPS models
gps-nmea-rtk-pmtkNTRIP-based RTK GPS models using I2C (experimental)
gps-nmea-rtk-serialNTRIP-based RTK GPS models using serial communication (experimental)
dual-gps-rtkA movement sensor that calculates compass heading from two GPS movement sensors
imu-witIMUs manufactured by WitMotion
accel-adxl345The Analog Devices ADXL345 digital accelerometer
gyro-mpu6050A gyroscope/accelerometer manufactured by TDK InvenSense
mergedA model that allows you to aggregate the API methods supported by multiple sensors into a singular sensor client, effectively merging the models of the individual resources
wheeled-odometryA model that uses encoders to get an odometry estimate from a wheeled base
fakeUsed to test code without hardware

Modular resources

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

For configuration information, click on the model name:

Model
Description

Micro-RDK

If you are using the micro-RDK, navigate to Micro-RDK Movement Sensor for supported model information.

Control your movement 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 movement sensor called "my_movement_sensor" configured as a component of your machine. If your movement sensor has a different name, change the name in the code.

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

from viam.components.movement_sensor import MovementSensor
import (
  "go.viam.com/rdk/components/movementsensor"
)

API

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 Method
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
GetGeometriesGet all the geometries associated with the movement sensor in its current configuration, in the frame of the movement sensor.all models
DoCommandSend or receive model-specific commands.all models
CloseSafely shut down the resource and prevent further use.all models

GetPosition

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

Supported by GPS models.

Parameters:

  • None

Returns:

  • (GeoPoint): Abstract base class for protocol messages, containing latitude and longitude as floats.
  • (float): Altitude in meters.

For more information, see the Python SDK Docs.

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

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:

  • (geo.Point): Contains the current latitude and longitude as floats.
  • (float64): The altitude in meters.
  • (error): An error, if one occurred.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(
    robot, "my_movement_sensor")

// Get the current position of the movement sensor.
position, err := myMovementSensor.Position(context.Background(), nil)

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.

Parameters:

  • None

Returns:

  • (Vector3): A 3D vector containing three floats representing the linear velocity in the x, y and z directions in meters per second.

For more information, see the Python SDK Docs.

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

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.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

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.

Parameters:

  • None

Returns:

  • (Vector3): A 3D vector containing three floats representing the angular velocity about the x, y and z axes in degrees per second.

For more information, see the Python SDK Docs.

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

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 angular velocity about the x, y and z axes in degrees per second.
  • (error): An error, if one occurred.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

// 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

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.

Parameters:

  • None

Returns:

  • (Vector3): 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).

For more information, see the Python SDK Docs.

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

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.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

// Get the x component of linear acceleration
xAngVel := linAccel.X

GetCompassHeading

Report the current compass heading in degrees.

Supported by GPS models.

Parameters:

  • None

Returns:

  • (float): Compass heading in degrees (between 0 and 360).

For more information, see the Python SDK Docs.

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

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.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

GetOrientation

Report the current orientation of the sensor.

Supported by IMU models.

Parameters:

  • None

Returns:

  • (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.

For more information, see the Python SDK Docs.

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

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): Orientation is an interface used to express the different parameterizations of the orientation of the movement sensor in 3D Euclidean space.
  • (error): An error, if one occurred.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

// Get the orientation vector (a unit vector pointing in the same direction as the sensor and theta, an angle representing the sensor's rotation about that axis).
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)

GetProperties

Get the supported properties of this sensor.

Parameters:

  • None

Returns:

  • (Properties): The supported properties of the movement sensor.

For more information, see the Python SDK Docs.

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

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.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

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:

  • None

Returns:

  • (MovementSensor.Accuracy): The reliability metrics of the movement sensor, which vary depending on model. This type contains the following fields:
    • accuracy (Mapping[string, float]): 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 floats.
    • position_hdop (Optional[float]): Horizontal Dilution of Precision (HDOP) value. It indicates the level of accuracy of horizontal measurements. Lower values indicate improved reliability of positional measurements.
    • position_vdop (Optional[float]): 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.
    • position_nmea_gga_fix (Optional[NmeaGGAFix]): An integer value representing the quality of the NMEA fix. See Novatel documentation for the meaning of each fix value.
    • compass_degrees_error (Optional[float]): 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.

For more information, see the Python SDK Docs.

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

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.

For more information, see the Go SDK docs.

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

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

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.

Parameters:

  • None

Returns:

  • (Mapping [str, Any]): An object containing the measurements from the sensor. Contents depend on sensor model and can be of any type.

For more information, see the Python SDK Docs.

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

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.

For more information, see the Go SDK docs for Sensor (because Readings is part of the general sensor API that movement sensor wraps).

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

// Get the latest readings from the movement sensor.
readings, err := myMovementSensor.Readings(context.Background(), nil)

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

  • (List[Geometry]): The geometries associated with the movement sensor, in any order.

For more information, see the Python SDK Docs.

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

DoCommand

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

Parameters:

Returns:

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

reset_dict = {
  "command": "reset",
  "example_param": 30
}

do_response = await my_movement_sensor.do_command(reset_dict)

For more information, see the Python SDK Docs.

Parameters:

Returns:

myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

resp, err := myMovementSensor.DoCommand(ctx, map[string]interface{}{"command": "reset", "example_param": 30})

For more information, see the Go SDK Code.

Close

Safely shut down the resource and prevent further use.

Parameters:

  • None

Returns:

  • None
my_movement_sensor = MovementSensor.from_robot(robot, "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.
myMovementSensor, err := movementsensor.FromRobot(robot, "my_movement_sensor")

err := myMovementSensor.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 on the Viam Community Slack and we will be happy to help.

Next steps

Try adding a movement sensor to your mobile robot and writing some code with our SDKs to implement closed-loop movement control for your machine.

Or, try configuring data capture on your movement sensor.

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