Configure a Wheeled Odometry Movement Sensor

Configure a wheeled-odometry movement sensor to implement wheeled odometry on your machine.

Wheeled odometry is the estimation of the rate of change of position, orientation, linear velocity, and angular velocity using the dimensions of a base, calculated by measuring the movement of the motors through encoders. Because of this method of estimation, you don’t have to have a specific piece of movement sensor hardware to implement wheeled-odometry on your machine. This model uses encoders from position reporting motors to get an odometry estimate of a wheeled base as it moves.

With a configured wheeled-odometry movement sensor, your machine calculates an estimation of the position, orientation, linear velocity, and angular velocity of the wheeled base each time time_interval_msec elapses during a session. You can access these readings through the movement sensor API. For the best accuracy with odometry calculations, it is recommended you configure a time interval of less than 1000 milliseconds.

After configuring a wheeled-odometry movement sensor, you can operate your base with Viam’s built-in services like the navigation service.

Set-up requirements

To prepare your machine, attach encoders to each of the position-reporting motors on your base to measure their rotation.

  • Select motors that can report their own position, like an encoded roboclaw or gpio motors with encoders, or the odrive module. You can access this property of a configured motor through the motor API’s GetProperties().
  • Configure your rover as a wheeled base component. Make sure to configure the base width and circumference, as these measurements as a property of the base are vital for accurate odometry estimations by your movement sensor. This movement sensor accesses these values through the base’s GetProperties() API method.
  • Configure each of the position-reporting motors as motor components.
  • Then, proceed to configure a wheeled-odometry movement sensor with the name of each of the motor components.

Configuration

Navigate to the Config tab of your machine’s page in the Viam app. Click on the Components subtab and click Create component. Select the movement-sensor type, then select the wheeled-odometry model. Enter a name for your movement sensor and click Create.

Creation of an `wheeled-odometry` movement sensor in the Viam app config builder.

Copy and paste the following attribute template into your movement sensor’s Attributes box. Then remove and fill in the attributes as applicable to your movement sensor, according to the table below.

{
  "base": "<your-base-name>",
  "left_motors": ["<your-base-left-motor-name-1>", "<your-base-left-motor-name-2>"],
  "right_motors": ["<your-base-right-motor-name-1", "your-base-right-motor-name-2>"],
  "time-interval-msec": <number>
}
{
  "base": "my_wheeled_base",
  "left_motors": ["leftm1", "leftm2"],
  "right_motors": ["rightm1", "rightm2"]
}
{
  "components": [
    {
      "name": "<your-wheeledodometry-movement-sensor-name>",
      "model": "wheeled-odometry",
      "type": "movement_sensor",
      "namespace": "rdk",
      "attributes": {
        "base": "<your-base-name>",
        "left_motors": ["<your-base-left-motor-name-1>", "<your-base-left-motor-name-2>"],
        "right_motors": ["<your-base-right-motor-name-1", "your-base-right-motor-name-2>"],
        "time-interval-msec": <number>
      }
    }
  ]
}
{
  "components": [
    {
      "name": "my-wheeled-odometer",
      "model": "wheeled-odometry",
      "type": "movement_sensor",
      "namespace": "rdk",
      "attributes": {
        "base": "my_wheeled_base",
        "left_motors": ["leftm1", "leftm2"],
        "right_motors": ["rightm1", "rightm2"]
      }
    }
  ]
}

Attributes

The following attributes are available for wheeled-odometry movement sensors:

NameTypeInclusionDescription
basestringRequiredThe name of the base to which the encoders making up this movement sensor are wired.
left_motorsobjectRequiredA list containing the name of each of the bases’ left position-reporting motors.
right_motorsobjectRequiredA list containing the name of each of the bases’ right position-reporting motors.
time_interval_msecnumberOptionalThe time in milliseconds between each wheeled odometry calculation.
Default: 500.0

Test the movement sensor

After you configure your movement sensor, navigate to the Control tab and select the dedicated movement sensor dropdown panel. This panel presents the data collected by the movement sensor.



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.