Movement Sensor Component
A movement sensor component is a sensor that gives data on where a robot is and how fast it is moving. Examples of movement sensors include global positioning systems (GPS), inertial measurement units (IMUs), accelerometers and gyroscopes.
Configuration
Viam supports several different models of GPS, IMU and accelerometer. Click the model names below for configuration information:
Model | Description |
---|---|
gps-nmea | NMEA-based GPS models |
gps-nmea-rtk-pmtk | NTRIP-based RTK GPS models using I2C (experimental) |
gps-nmea-rtk-serial | NTRIP-based RTK GPS models using serial communication (experimental) |
imu-wit | IMUs manufactured by WitMotion |
imu-vectornav | IMUs manufactured by VectorNav |
accel-adxl345 | The Analog Devices ADXL345 digital accelerometer |
viam_visual_odometry | A modular resource that derives movement data from a camera stream |
gyro-mpu6050 | A gyroscope/accelerometer manufactured by TDK InvenSense |
merged | A 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-odometry | A model that uses encoders to get an odometry estimate from a wheeled base |
fake | Used to test code without hardware |
Control your movement sensor with Viam’s client SDK libraries
To get started using Viam’s SDKs to connect to and control your robot, go to your robot’s page on the Viam app, navigate to the Code sample tab, select your preferred programming language, and copy the sample code generated.
Location secret
By default, the sample code does not include your robot location secret. We strongly recommend that you add your location secret as an environment variable and import this variable into your development environment as needed.
To show your robot’s location secret in the sample code, toggle Include secret on the Code sample tab. You can also see your location secret on the locations page.
Caution
Do not share your location secret, part secret, or robot address publicly. Sharing this information could compromise your system security by allowing unauthorized access to your robot, or to the computer running your robot.
When executed, this sample code will create a connection to your robot as a client. Then control your robot 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 robot.
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.
Tip
You can run GetProperties
on your sensor for a list of its supported methods.
Method Name | Description | Models That Support This Method |
---|---|---|
GetPosition | Get the current latitude, longitude and altitude. | GPS models |
GetLinearVelocity | Get the current linear velocity as a 3D vector. | GPS models |
GetAngularVelocity | Get the current angular velocity as a 3D vector. | IMU models and gyro-mpu6050 |
GetLinearAcceleration | Get the current linear acceleration as a 3D vector. | IMU models, accel-adxl345 , and gyro-mpu6050 |
GetCompassHeading | Get the current compass heading in degrees. | GPS models and imu-vectornav |
GetOrientation | Get the current orientation. | IMU models |
GetProperties | Get the supported properties of this sensor. | all models |
GetAccuracy | Get the accuracy of the various sensors. | GPS models |
GetReadings | Obtain the measurements/data specific to this sensor. | all models |
DoCommand | Send or receive model-specific commands. | 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 and imu-vectornav
.
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:
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
, andtheta
, 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:
- (*movementsensor.Properties): The supported properties of the movement sensor.
- (error): An error, if one occurred.
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 accuracy of the sensor (and/or precision, depending on the sensor model).
Supported by GPS models.
Parameters:
- None
Returns:
- (Dict[str, float]): The accuracy and/or precision of the sensor, if supported. Contents depend on sensor model.
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:
- (map[string]float32): The accuracy and/or precision of the sensor, if supported. Contents depend on sensor model.
- (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)
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:
command
(Dict[str, Any]): The command to execute.
Returns:
- (Dict[str, Any]): Result of the executed command.
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:
ctx
(Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries.cmd
(map[string]interface{}): The command to execute.
Returns:
- (map[string]interface{}): Result of the executed command.
- (error): An error, if one occurred.
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.
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 robot.
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.
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!