Configure a Merged Movement Sensor

The merged movement sensor model is an abstraction that combines data from multiple movement sensors. This allows you to aggregate the API methods supported by multiple sensors into a singular sensor client.

This is especially useful if you want to get readings of position and orientation or linear and angular velocity at the same time, which are normally separately supported and returned by GPS or IMU models, respectively.

To reduce velocity error when your machine is using the navigation service, aggregate Position() from a GPS and Orientation() from an IMU movement sensor in a merged model.

Configure a navigation service to use your merged sensor to navigate.

Before configuring a merged movement sensor, configure each movement sensor you want to merge as an individual component according to its model’s configuration instructions. Reference the name you configure for each individual component in the merged sensor’s configuration attributes:

• Config Builder
• JSON Template
• JSON Example

Navigate to the CONFIGURE tab of your machine’s page in the Viam app. Click the + icon next to your machine part in the left-hand menu and select Component. Select the movement-sensor type, then select the merged model. Enter a name or use the suggested name for your movement sensor and click Create.

Fill in the attributes as applicable to your movement sensor, according to the table below. For example:

{
  "components": [
    {
      "name": "<your-sensor-name>",
      "model": "merged",
      "type": "movement_sensor",
      "namespace": "rdk",
      "attributes": {
        "position": ["<your-gps-sensor-name-1>", "<your-gps-sensor-name-2>"],
        "orientation": ["<your-imu-sensor-name-1>"],
        "compass_heading": ["<your-gps-sensor-name-1>"],
        "angular_velocity": ["<your-imu-sensor-name-1>"],
        "linear_velocity": ["<your-gps-sensor-name-1>"],
        "linear_acceleration": ["<your-accelerometer-sensor-name-1>"]
      },
      "depends_on": []
    }
  ]
}

// { "components": [ { ... },
{
  "name": "<your-sensor-name>",
  "model": "merged",
  "type": "movement_sensor",
  "namespace": "rdk",
  "attributes": {
    "position": ["gps1"],
    "orientation": ["imu-wit"],
    "compass_heading": ["gps1"],
    "angular_velocity": ["imu-wit", "mpu6050"],
    "linear_velocity": ["gps1"],
    "linear_acceleration": ["adxl345"]
  },
  "depends_on": []
}

Attributes

Configure an array of the name of each movement sensor you want to add to your machine as a merged resource in the attributes of the merged movement sensor model:

• The name of each attribute represents the Property that the particular movement sensor supports, or the type of reading or measurement that it takes.
• Get the properties supported by each model from its model configuration documentation, or by calling GetProperties() on the sensor.
• Put the name of each movement sensor into the attribute array for the type of reading it supports. You can use the same sensor for multiple attributes if it supports multiple properties.

Note that only one sensor from each array can be used to retrieve each type of reading. Your machine uses the first sensor in the array that has implemented the relevant API method in its model and does not raise an error at runtime. For instance, in the JSON Example above, if both "imu-wit" and "mpu6050" support returning angular_velocity, "mpu6050" is only used to read angular velocity on the machine if "imu-wit" returns an error at runtime.

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.

Troubleshooting

If your movement sensor is not working as expected, follow these steps:

1. Check your machine logs on the LOGS tab to check for errors.
2. Review this movement sensor model’s documentation to ensure you have configured all required attributes.
3. Click on the TEST panel on the CONFIGURE or CONTROL tab and test if you can use the movement sensor there.

If none of these steps work, reach out to us on the Community Discord and we will be happy to help.

Next steps

For more configuration and usage info, see: