Machine configuration

When you add components through the Viam app, you’re building a JSON configuration that tells viam-server what hardware is attached and how to talk to it. Understanding this configuration structure helps you work faster. You can edit JSON directly, copy configurations between machines, and debug issues by reading the raw config.

Configuration blocks

Every component in your machine’s configuration is a JSON block with these fields:

FieldWhat it does
nameA name for this component, unique across the machine (details). Your code references the component by this name.
apiThe component type, in the form rdk:component:<type> (for example, rdk:component:arm).
modelThe specific implementation, in the form namespace:family:name (for example, viam:ufactory:xArm6). Built-in models use rdk:builtin:name (for example, rdk:builtin:gpio).
attributesModel-specific settings that control how to connect to the hardware and how it should behave.
depends_onOther components this one requires (for example, a motor depends on a board).
frameOptional spatial relationship to a parent component, used by the motion service.

Example: a motor controlled by a board

Here’s a simple configuration with a Raspberry Pi board and a DC motor connected to its GPIO pins:

{
  "components": [
    {
      "name": "my-board",
      "api": "rdk:component:board",
      "model": "viam:raspberry-pi:rpi5",
      "attributes": {}
    },
    {
      "name": "my-motor",
      "api": "rdk:component:motor",
      "model": "gpio",
      "attributes": {
        "pins": {
          "a": "13",
          "b": "15",
          "pwm": "12"
        },
        "board": "my-board"
      }
    }
  ],
  "modules": [
    {
      "type": "registry",
      "name": "viam_raspberry-pi",
      "module_id": "viam:raspberry-pi",
      "version": "latest"
    }
  ]
}

A few things to note:

  • The board uses viam:raspberry-pi:rpi5 from the Viam registry. The modules section tells viam-server to download and run that module. Other Pi variants (rpi, rpi4, rpi3, and so on) are available from the same module.
  • The motor uses gpio, a built-in model for DC motors driven by GPIO pins. The pins attribute maps the motor’s control wires to specific board pins.
  • The motor’s board attribute references my-board, so viam-server automatically initializes the board before the motor. An explicit depends_on field is not required when attributes already reference the other component.

Modules section

When you use a model from the Viam registry (not built into viam-server), your configuration includes a modules section that tells viam-server what to download:

FieldWhat it does
typeAlways "registry" for modules from the Viam registry.
nameA local name for the module (used in logs).
module_idThe registry identifier, in the form namespace:module-name.
versionThe version to use. Use a specific version for production; "latest" for development.

You don’t need to write this JSON by hand. When you add a module model through the Viam app, the modules section is created automatically.

Editing configuration

You can edit your machine’s configuration in two ways:

  • Builder UI: the visual editor in the Viam app. Best for adding components one at a time and using form fields for attributes.
  • JSON mode: click JSON in the left-hand menu on the CONFIGURE tab to see and edit the raw JSON. Best for copying configurations, making bulk changes, or understanding exactly what’s configured.

Both views edit the same underlying configuration. Changes in one are reflected in the other.

If someone else saves the configuration while you have unsaved edits, or you save it from another browser tab, Save is replaced by Config out of date with Review and Discard. Fragment configurations work the same way. Click Discard to drop your edits and load the latest saved configuration, or click Review to open the Configuration out of date dialog. The dialog shows how the saved configuration differs from your edits (and who changed it, when known), and offers these choices:

  • Merge changes: combine your edits with the latest saved configuration. The dialog offers this, on its Merge tab, only when the two can be merged safely.
  • Save anyway: keep your edits and overwrite the other change. When the dialog shows tabs, this is on the Overwrite tab.
  • Discard changes and reload: drop your edits and load the latest saved configuration.

In either view, you can also describe a change in plain language and have the AI assistant stage it for you to review and save.

Related