Configure a Smart Machine

Before you can program a smart machine, you must configure it.

A machine’s configuration defines the resources (hardware and software services) it has access to, as well as any relevant parameters for those resources. You can configure the following resources:

• Components: Components are the hardware of your machine.
• Services: Services are the software that runs on your machine.
• Processes: Processes automatically run specified scripts when the machine boots.
• Modules: Modules provide modular resources, which are a way to add resource types or models that are not built into Viam.
• Remote parts: Remotes are a way to connect two separate machines so one can access the resources of the other.
• Sub-parts: Sub-parts are a way to connect two computers inside the same machine.
• Fragments: Fragments are a way of sharing and managing identical configuration files (or parts of config files) across multiple machines.
• Frames: Frames hold reference frame information for the relative position of components in space.
• Webhooks: Webhooks allow you to trigger actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes.
• Network: Networking options allow you to configure the bind address for accepting connections.

To start configuring, go to the Viam app and create a new machine. Open the part status dropdown menu in the top left corner of the page, next to the machine’s name. Click View setup instructions to open the setup instructions. Follow the appropriate instructions for your machine’s architecture.

The setup steps copy your machine’s credentials to your machine. When you turn on your machine, viam-server starts up and uses the provided credentials to fetch its full config from the Viam app. Once the machine has a configuration, it caches it locally and can use the configuration for up to 60 days. The machine checks for new configurations every 15 seconds and changes its configuration automatically when a new configuration is available. All communication happens securely over HTTPS using secret tokens that are in a machine’s configuration.

After you have completed the setup steps and successfully connected to your machine, go to the CONFIGURE tab to start adding to the configuration.

The CONFIGURE tab

The CONFIGURE tab on the Viam app is the place to configure everything about your machine.

You can switch between Builder, JSON, and Frame mode by clicking on the icon in the upper left-hand corner:

• Builder mode provides a graphical interface for configuring your machine resources.
• JSON mode provides a text editing field where you can write and edit the config manually.
• Frame mode provides a graphical interface for configuring and visualizing the relative position of components in space. For more information, see the Frame System documentation.

Regardless of the editing mode you choose, Viam stores the configuration file in JSON (JavaScript Object Notation).

If you add components in Builder mode and click Save in the top right corner of the screen, you can switch to JSON and see the JSON that has been generated by the builder.

{
  "components": [
    {
      "name": "local",
      "model": "pi",
      "type": "board",
      "namespace": "rdk",
      "attributes": {},
      "depends_on": []
    },
    {
      "name": "my-motor",
      "model": "gpio",
      "type": "motor",
      "namespace": "rdk",
      "attributes": {
        "pins": {
          "a": "13",
          "b": "15"
        },
        "board": "local",
        "max_rpm": 120
      },
      "depends_on": []
    },
    {
      "name": "my_camera",
      "model": "webcam",
      "type": "camera",
      "namespace": "rdk",
      "attributes": {
        "video_path": "video0"
      }
    }
  ],
  "services": [
    {
      "name": "detector",
      "type": "vision",
      "attributes": {
        "register_models": [
          {
            "parameters": {
              "segment_size_px": 200,
              "hue_tolerance_pct": 0.05,
              "detect_color": "#19FFD9"
            },
            "type": "color_detector",
            "name": "green_detector"
          }
        ]
      }
    }
  ],
  "modules": []
}

Components

Components represent the pieces of hardware on your machine that you want to control with Viam. To add a new component, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Component or hit C. Search for and select your desired model.

You must configure each component with a type, a model, a name, attributes, and dependencies:

• type: The broad component category, such as motor, arm or camera. Components of a given type have a common API.

• model: Indicates the more specific category of hardware. Components of the same model are supported using the same low-level code.

• name: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can either accept the suggested default name when creating a component or choose a unique name for a component. The name must start with a letter or number and only contain letters, numbers, dashes, and underscores with a max length of 60.

• attributes: A struct to define things like how the component is wired to the machine, its dimensions, and other specifications; attributes vary widely between models. See the component documentation for a given component type and model for more details.

• depends_on: Any components that a given component relies upon, and that must be initialized on boot before this component is initialized. Many built-in components have convenient implicit dependencies, in which case depends_on can be left blank. For example, a gpio motor depends on the board to which it is wired, but it has a dedicated board attribute and viam-server will automatically initialize that board before it looks for the motor.

If you are configuring several similar components, you can click … in the upper-right of a component’s configuration pane, then select the Duplicate button to create a new identical component beneath your existing one. Be sure to edit the duplicated component to change any parameters that are unique to the new component, such as its name and pins.

To delete a component, click … in the upper-right of the component’s configuration pane, then select the trash can icon. Confirm that you are sure.

For specific information on how to configure each supported component type, see the components documentation.

Services

Services are built-in software packages that make it easier to add complex capabilities such as motion planning or object detection to your machine. To add a new service, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Service or hit S. Search for and select your desired model.

You must configure a service with a name and a type:

• type: specifies which of the Viam services you want to use on your machine, such as the vision service or the motion service.
• name: serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource. You can accept the suggested default name when creating a service or choose a choose any unique name for a service. The name must start with a letter or number and can only contain letters, numbers, dashes, and underscores with a max length of 60.

The other aspects of configuring a service are highly specific to the type of service. See the services documentation for more information.

Processes

To automatically run a specified command when the machine boots, configure a process. You can configure any command, for example one that executes a binary or a script, to run as a process.

To add a new process, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Process. Find more information in the processes documentation.

Modules

Modular resources are a way to add resource types or models that are not built into Viam. Many models are available in the registry and you are able to add them as components or services.

To add a module that is not in the registry and is local to your machine, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Local module. Follow the instructions in our registry documentation to configure the module.

Remote parts

Configuring a remote part is a way to connect two separate machines so one can access the resources of the other.

To configure a remote part, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Remote part. Find more information in our machine parts documentation.

Sub-parts

Configure a sub-part to connect two computers inside the same machine.

To configure a sub-part, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Sub-part. Find more information in our machine parts documentation.

Fragments

You can use fragments to share similar resource configuration files across multiple machines in your fleet. For example, if you have multiple machines with the same motor hardware, wired the same way, you can create a fragment to configure that motor and share it easily across all of your machines, without needing to individually configure the motor component for each machine.

To configure a fragment, click the + icon next to your machine part in the left-hand menu of the CONFIGURE tab and select Insert fragment. See Use Fragments to Configure a Fleet for more information on creating and deploying fragments.

Frames

The frame system holds reference frame information for the relative position of components in space.

Clicking on the Frame mode to visualize and configure the relative positions of components. Find more information in the frame system documentation.

Webhooks

Webhooks allow you to trigger actions when certain types of data are sent from your machine to the cloud, or when the internet connectivity of your machine changes. For example, you can configure a webhook to send you a notification when your robot’s sensor collects a new reading.

See Configure a Webhook for more information on webhooks.

Network

Expand a part’s configuration card to open its network configuration interface:

You can configure the address viam-server binds to for accepting connections. By default, viam-server binds to 0.0.0.0:8080 when managed by the Viam app or when authentication and TLS are enabled. You can also set the heartbeat window.

Configuration History

The Viam app keeps a record of your configuration changes, allowing you to revert to earlier configurations if needed.

To see the configuration history for a machine part, click on the History link at the top right corner of the machine part’s card in the Viam app.

To restore to an earlier version of your configuration, click the Restore version button next to the desired configuration.

Troubleshooting

If you run into issues, here are some things to try:

• Check the LOGS tab to view log messages and errors from viam-server. You can also access the local log file on your machine if needed.
• Make sure all configured components are saved to your config. If they aren’t, you will see an Unsaved changes note next to the Save button in the top right corner of the page.
• Try restarting viam-server by navigating to the app’s CONFIGURE tab in Builder mode, clicking the … menu on the right side of the machine part’s card, and selecting Restart part. It takes a few minutes for the server to shut down and restart.
• If you need to revert to an earlier configuration, use the Configuration History to restore to an earlier version.
• Make sure the issue is not hardware related. Some things to check are that the machine has adequate power, all wires are properly connected, and no chips or other hardware components are shorted or overheated.
• See Troubleshooting for additional troubleshooting steps.

• You can also ask questions in the Community Discord and we will be happy to help.

Local setup

Configuring viam-server with the Viam app allows you to make use of the cloud features of Viam:

• Fleet Management
• Data Management
• Machine Learning

However, if you are configuring a machine that can never connect to the internet, you can create a local configuration file on your machine. A locally-configured machine will not be able to access Viam’s cloud features.

Next steps

After configuring your machine, you can use the Viam SDKs to program and control your machine.

If you want to try configuring a machine but don’t have any hardware on hand, try the Build a Mock Robot tutorial.