Edit

Configuration Fragments

If you have multiple machines with similar configurations, you can use a fragment to configure all of the machines at the same time. Fragments are a way of sharing and managing machine configurations across multiple machines.

If there are differences between your machines, you can use a fragment to quickly configure the resources that are the same between machines. You can then configure the differing resources separately, outside of the fragment. For example, if you have multiple similar rovers but one has an arm attached, you can add the rover configuration fragment (including the motors and base components), and then configure the arm on just that one rover.

When you or one of your collaborators edit a fragment that you’ve already deployed to one or more machines, the Viam app updates the configuration on each deployed machine that uses that fragment.

Alert

Be cautious when making changes to fragments that have been deployed to production machines. We recommend that you create a duplicate fragment, make your desired change to that second fragment, and then deploy that fragment to a test machine that is configured identically to your production machines.

Once you are confident that your configuration change works as expected, you can safely make the same change to the fragment in use on your production fleet, and the Viam app will deploy that change to all machines using that fragment.

If you attempt to delete a fragment that is currently deployed to a machine, you will receive an error message advising that the fragment is in use, but you can still delete the fragment if desired. You can see the number of machines using your fragment from the fragments page in the Viam app.

You must be an organization owner to create fragments associated with a given organization.

A fragment can define one, several, or all resources on a machine. You can add multiple fragments to a single machine, and you can add additional resources to a machine that has already been configured with a fragment.

Create and use a fragment

Get started with this how-to guide:

Modify the config of a machine that uses a fragment

If you need to modify the config of one or a few machines that use a fragment, you can overwrite fields of the fragment.

When you add a fragment to a machine, the configuration of components and services included in a fragment are read-only. Any changes made by overwriting them do not change the fragment itself.

If you need to make changes to all machines that use a fragment, modify the fragment itself instead.

Support Notice

Fragment overwrites are not supported for the modification of trigger configuration. You can create a trigger with a fragment but you cannot modify it with fragment_mods.

Config Builder
JSON

To overwrite fields of a fragment, make edits to the component or service configuration just as you would for a non-fragment resource.

When you make edits to the configuration of component or service that was configured using a fragment, the Viam app builder automatically adds an overwrite to your config. If you have made edits, you will see an edited from FRAGMENT NAME indicator in the upper right corner of the edited component or service card.

A motor config card with “edited from SCUTTLE101” in the upper right corner.

You can modify fragment fields in your machine’s raw JSON config by using update operators. Viam supports all update operators except for $setOnInsert, $, $[], and $[<identifier>].

To configure fragment overwrites manually instead of using the builder UI:

Navigate to your machine’s CONFIGURE tab.
Switch to JSON mode.
Add a top-level section called "fragment_mods" (alongside the other top-level sections like "components" and "fragments"):

Template
Full example

  "fragment_mods": [
    {
      "fragment_id": "<YOUR FRAGMENT ID>",
      "mods": [
        {
          <INSERT YOUR MODS HERE>
        }
      ]
    }
  ],

This example assumes the fragment with ID abcd7ef8-fa88-1234-b9a1-123z987e55aa contains a motor configured with "name": "motor1".

{
  "components": [],
  "fragment_mods": [
    {
      "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
      "mods": [
        {
          "$set": {
            "components.motor1.attributes.max_rpm": 1818,
            "components.motor1.attributes.pins.a": 30,
            "components.motor1.attributes.board": "local"
          }
        },
        {
          "$unset": {
            "components.motor1.attributes.pins.pwm": 0
          }
        }
      ]
    }
  ],
  "fragments": ["abcd7ef8-fa88-1234-b9a1-123z987e55aa"]
}

Edit the fragment_id value to match the ID of the fragment you want to modify, for example "12345678-1a2b-9b8a-abcd987654321".
Add any update operators you’d like to apply to the fragment to the mods section. Click to view each example:

Change the name and attributes of a component

This example uses $set to make the following changes to the attributes of a motor named motor1:

Sets the max_rpm to 1818.
Changes the name of motor1 to my_motor. Note that this does not affect the other mods; you still use motor1 for them.
Sets the pin number for pin a to 30.
Sets the name of the board associated with this motor to local.

"fragment_mods": [
 {
   "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
   "mods": [
     {
       "$set": {
         "components.motor1.attributes.max_rpm": 1818,
         "components.motor1.name": "my_motor",
         "components.motor1.attributes.pins.a": 30,
         "components.motor1.attributes.board": "local"
       }
     }
   ]
 }
],

Remove an attribute

This example uses $unset to remove the pin number set for the pwm pin, so the motor no longer has a PWM pin set. In other words, it deletes the pwm pin field.

"fragment_mods": [
  {
    "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
    "mods": [
      {
       "$unset": {
         "components.motor1.attributes.pins.pwm": 0
       }
      }
    ]
  }
],

Modify dependencies

This example uses $set to assign a new list of dependencies to a component named rover_base2.

"fragment_mods": [
  {
    "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
    "mods": [
      {
       "$set": {
         "components.rover_base2.attributes.depends_on": ["local", "motor1"]
       }
      }
    ]
  }
],

Change motor pins from A and B to PWM and DIR

This example uses $rename to make the following changes to the attributes of a motor named motor1 in the fragment:

Retrieves the pin number for pin a and assigns that value to the PWM pin. Deletes the pins.a field.
Retrieves the pin number for pin b and assigns that value to the DIR pin. Deletes the pins.b field.

$rename is for changing an attribute’s key, not its value. If you want to change the name of a component (for example, motor1), use $set, as shown in the change the name of a component example.

"fragment_mods": [
 {
   "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
   "mods": [
     {
       "$rename": {
         "components.motor1.attributes.pins.a": "components.motor1.attributes.pins.pwm",
         "components.motor1.attributes.pins.b": "components.motor1.attributes.pins.dir"
       }
     }
   ]
 }
],

Change a camera path

This example uses $set to change the video path for a camera named camera-one in the fragment:

"fragment_mods": [
  {
    "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
    "mods": [
      {
        "$set": {
          "components.camera-one.attributes.video_path": "0x11100004a12345"
        }
      }
    ]
  }
],

Modify data sync settings

This example uses $set to change the sync interval for a data management service named data-management in the fragment:

"fragment_mods": [
  {
    "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
    "mods": [
      {
        "$set": {
          "services.data-management.attributes.sync_interval_mins": "0.5"
        }
      }
    ]
  }
],

Pin a module version

This example uses $set to set version update settings for a module named custom-sensor in the fragment:

"fragment_mods": [
  {
    "fragment_id": "abcd7ef8-fa88-1234-b9a1-123z987e55aa",
    "mods": [
      {
        "$set": {
          "modules.custom-sensor.version": "1.8.0"
        }
      }
    ]
  }
],

Here are the version options:

To update with new minor releases of the same major release branch, use "^<major version number>", for example "^1"
To update with new patch releases of the same minor release branch, use "~<minor version number>", for example "~1.8"
To always update with the latest release, use "latest"
To pin to a specific release, use "<version number>", for example "1.8.3"

Click Save in the upper right corner of the page to save your new configuration.
To check that your mods are working, view your machine’s debug configuration. In Builder mode on the CONFIGURE tab, select the … (Actions) menu to the right of your main part’s name in the left-hand panel and click the View debug configuration option to view the full configuration file.

After configuring fragment modifications, check your machine’s LOGS tab. If there are problems with fragment modifications, depending on the issue, your machine or some of its components may not work until the configuration is fixed.

If you need to restore the original fragment, click the … in the upper right corner of the card you modified, and click Revert changes.

Next steps

Viam provides several pre-made fragments which you can use as templates for writing your own fragments.

For an example of a fragment that configures multiple components and services, see the Viam Rover fragment.

For an example of creating a fragment and using it to configure a fleet of machines, see the air quality fleet tutorial:

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.

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!